@things-factory/headless-twin 10.1.8 → 10.1.11

package/dist-server/service/reference/twin-reference-reconciliation.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinReferenceReconciliation = 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");
+/* 한 연결·Twin·단위의 최신 번호 대사 상태. 과거 추이는 ingest window가, 현재 조치 판단은 이 표가 답한다. */
+let TwinReferenceReconciliation = class TwinReferenceReconciliation {
+};
+exports.TwinReferenceReconciliation = TwinReferenceReconciliation;
+tslib_1.__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    (0, type_graphql_1.Field)(type => type_graphql_1.ID),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.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 }),
+    tslib_1.__metadata("design:type", shell_1.Domain)
+], TwinReferenceReconciliation.prototype, "domain", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((e) => e.domain),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "domainId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "instanceId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "scope", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)(),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "status", 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 }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "sourceFirst", 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 }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "sourceLast", 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 }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "cursorSeq", 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 }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "firstSeqSeen", 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 }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "headMissing", 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 }),
+    tslib_1.__metadata("design:type", Number)
+], TwinReferenceReconciliation.prototype, "behind", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true }),
+    tslib_1.__metadata("design:type", String)
+], TwinReferenceReconciliation.prototype, "reason", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)(),
+    tslib_1.__metadata("design:type", Date)
+], TwinReferenceReconciliation.prototype, "checkedAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.CreateDateColumn)(),
+    tslib_1.__metadata("design:type", Date)
+], TwinReferenceReconciliation.prototype, "createdAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.UpdateDateColumn)(),
+    tslib_1.__metadata("design:type", Date)
+], TwinReferenceReconciliation.prototype, "updatedAt", void 0);
+exports.TwinReferenceReconciliation = TwinReferenceReconciliation = tslib_1.__decorate([
+    (0, typeorm_1.Entity)(),
+    (0, typeorm_1.Index)('uq_twin_reference_reconciliation_0', (e) => [e.domain, e.instanceId, e.scope], { unique: true }),
+    (0, typeorm_1.Index)('ix_twin_reference_reconciliation_0', (e) => [e.domain, e.instanceId, e.checkedAt], { unique: false }),
+    (0, type_graphql_1.ObjectType)({ description: 'Latest durable sequence reconciliation for one connected source scope. It reports only what numbered source ranges can prove; it never substitutes replay-prone ingest-window counts for source facts.' })
+], TwinReferenceReconciliation);
+//# sourceMappingURL=twin-reference-reconciliation.js.map

package/dist-server/service/reference/twin-reference-reconciliation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-reference-reconciliation.js","sourceRoot":"","sources":["../../../server/service/reference/twin-reference-reconciliation.ts"],"names":[],"mappings":"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","sourcesContent":["import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId, UpdateDateColumn } from 'typeorm'\nimport { Field, ID, Int, ObjectType } from 'type-graphql'\nimport { Domain } from '@things-factory/shell'\n\n/* 한 연결·Twin·단위의 최신 번호 대사 상태. 과거 추이는 ingest window가, 현재 조치 판단은 이 표가 답한다. */\n@Entity()\n@Index('uq_twin_reference_reconciliation_0', (e: TwinReferenceReconciliation) => [e.domain, e.instanceId, e.scope], { unique: true })\n@Index('ix_twin_reference_reconciliation_0', (e: TwinReferenceReconciliation) => [e.domain, e.instanceId, e.checkedAt], { unique: false })\n@ObjectType({ description: 'Latest durable sequence reconciliation for one connected source scope. It reports only what numbered source ranges can prove; it never substitutes replay-prone ingest-window counts for source facts.' })\nexport class TwinReferenceReconciliation {\n  @PrimaryGeneratedColumn('uuid') @Field(type => ID) readonly id: string\n  @ManyToOne(type => Domain) @Field(type => Domain, { nullable: true }) domain?: Domain\n  @RelationId((e: TwinReferenceReconciliation) => e.domain) domainId?: string\n  @Column() @Field() instanceId: string\n  @Column() @Field() scope: string\n  @Column() @Field() status: 'aligned' | 'gap' | 'unknown'\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) sourceFirst?: number\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) sourceLast?: number\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) cursorSeq?: number\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) firstSeqSeen?: number\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) headMissing?: number\n  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) behind?: number\n  @Column({ nullable: true }) @Field({ nullable: true }) reason?: string\n  @Column() @Field() checkedAt: Date\n  @CreateDateColumn() createdAt?: Date\n  @UpdateDateColumn() updatedAt?: Date\n}\n"]}

package/dist-server/service/twin-lifecycle/twin-lifecycle-mutation.d.ts

@@ -45,6 +45,15 @@ export declare class TwinLifecycleMutation {
      * 그것을 「이름을 바꿨다」로 보고하면 거짓이다. 지우고 싶으면 그 뜻의 문이 따로 있어야 한다.
      */
     renameTwinInstance(instanceId: string, name: string, context: ResolverContext): Promise<any>;
+    /**
+     * 폐기 전에 사라질 것을 읽는다.
+     *
+     * 삭제는 레지스트리 행 하나만 없애는 일이 아니다. `TwinEngine.remove` 는 같은 트윈의 저널도
+     * purge 한다. 그래서 확인 창이 추측한 숫자를 쓰지 않고, **삭제와 같은 domain·instance 범위**를
+     * 직접 센다. 저널이 비어 있는 트윈도 `0` 과 null 기간을 돌려준다 — 없는 기록을 기간으로
+     * 꾸며내면 "아무것도 안 지워진다"와 "언제부터인지 모른다"가 섞인다.
+     */
+    twinDeletionPreview(instanceId: string, context: ResolverContext): Promise<any | null>;
     /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */
     deleteTwinInstance(instanceId: string, context: ResolverContext): Promise<boolean>;
     /** 관리 목록 — 등록된 인스턴스 전체(kind/status/running/revision/노드·무버 수). 데이터 없으면 빈 배열. */

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

@@ -8,6 +8,7 @@ const index_js_1 = require("../../engine/index.js");
 /* 정책 읽기는 그 모듈에서 직접 가져온다 — 다른 소비처(`reference-resolver`)와 같은 길이다. */
 const restart_policy_js_1 = require("../../engine/restart-policy.js");
 const twin_instance_js_1 = require("../twin-instance/twin-instance.js");
+const twin_event_js_1 = require("../twin-event/twin-event.js");
 /* 도메인 어휘 카탈로그(시스템별 노드 타입) — 커널이 SSOT. 앱/UI 는 이걸 소싱하고 재선언하지 않는다(방언 금지).
  * 조합은 domain-catalog.ts 가 소유 — 리졸버와 서버측 소비자(board-ai 도구 등)가 같은 형태를 본다. */
 const domain_catalog_js_1 = require("./domain-catalog.js");
@@ -120,6 +121,35 @@ let TwinLifecycleMutation = class TwinLifecycleMutation {
         /* 도는 런타임은 이름을 쓰지 않는다(식별자로 돈다) — 그래서 정지·기동이 필요하지 않다. */
         return { instanceId, name: next, previous: before || null, changed: true };
     }
+    /**
+     * 폐기 전에 사라질 것을 읽는다.
+     *
+     * 삭제는 레지스트리 행 하나만 없애는 일이 아니다. `TwinEngine.remove` 는 같은 트윈의 저널도
+     * purge 한다. 그래서 확인 창이 추측한 숫자를 쓰지 않고, **삭제와 같은 domain·instance 범위**를
+     * 직접 센다. 저널이 비어 있는 트윈도 `0` 과 null 기간을 돌려준다 — 없는 기록을 기간으로
+     * 꾸며내면 "아무것도 안 지워진다"와 "언제부터인지 모른다"가 섞인다.
+     */
+    async twinDeletionPreview(instanceId, context) {
+        const domainId = context.state.domain.id;
+        const instance = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } });
+        if (!instance)
+            return null;
+        const journal = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent)
+            .createQueryBuilder('event')
+            .select('COUNT(event.id)', 'count')
+            .addSelect('MIN(event.eventTime)', 'firstEventAt')
+            .addSelect('MAX(event.eventTime)', 'lastEventAt')
+            .where('event.domain = :domainId', { domainId })
+            .andWhere('event.instanceId = :instanceId', { instanceId })
+            .getRawOne();
+        return {
+            instanceId,
+            name: instance.name ?? null,
+            journalCount: Number(journal?.count ?? 0),
+            firstEventAt: journal?.firstEventAt ?? null,
+            lastEventAt: journal?.lastEventAt ?? null
+        };
+    }
     /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */
     async deleteTwinInstance(instanceId, context) {
         await index_js_1.TwinEngine.remove(context.state.domain.id, instanceId);
@@ -235,6 +265,17 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:paramtypes", [String, String, Object]),
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinLifecycleMutation.prototype, "renameTwinInstance", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
+        nullable: true,
+        description: 'Describe what deleting one twin would purge before it is deleted: its registry identity and the count plus first/last event time of its journal. Null means this twin is not in the current domain.'
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinLifecycleMutation.prototype, "twinDeletionPreview", 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: 'Delete a twin instance: stop it, remove the registry entry and purge its event journal.' }),

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

@@ -1 +1 @@
-{"version":3,"file":"twin-lifecycle-mutation.js","sourceRoot":"","sources":["../../../server/service/twin-lifecycle/twin-lifecycle-mutation.ts"],"names":[],"mappings":"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","sourcesContent":["import { Arg, Ctx, Mutation, Query, Resolver, Directive} from 'type-graphql'\n\nimport { ScalarObject, getRepository } from '@things-factory/shell'\n\nimport { TwinEngine } from '../../engine/index.js'\n/* 정책 읽기는 그 모듈에서 직접 가져온다 — 다른 소비처(`reference-resolver`)와 같은 길이다. */\nimport { readRestartPolicy } from '../../engine/restart-policy.js'\nimport { TwinInstance } from '../twin-instance/twin-instance.js'\n\nimport type { TwinModelDef } from '@operato/ops-contract'\n\n/* 도메인 어휘 카탈로그(시스템별 노드 타입) — 커널이 SSOT. 앱/UI 는 이걸 소싱하고 재선언하지 않는다(방언 금지).\n * 조합은 domain-catalog.ts 가 소유 — 리졸버와 서버측 소비자(board-ai 도구 등)가 같은 형태를 본다. */\nimport { domainCatalog } from './domain-catalog.js'\n\n/*\n * 트윈 인스턴스 생명주기 채널 — 프로비저닝(상향, ADR-0015).\n * State/Command/Scenario 는 이미 running 인 인스턴스를 다루지만, 이 채널은 인스턴스 자체를 만들고/설정하고/없앤다.\n * 생명주기: provision(save, 미기동) → start → stop → delete. 모두 domain 스코프(context.state.domain.id).\n * model(TwinModelDef+layout)=구조, scenario=자극 은 분리 — 여기선 구조만 세운다. 자극은 **원본이 선언하고**\n * (`TwinReference.connectionConfig.scenario`) 기동이 싣거나, 원본의 구동 능력으로 태운다(ADR-0029 §4·§8).\n */\n@Resolver()\nexport class TwinLifecycleMutation {\n  /*\n   * `saveTwinInstance` 는 **없앴다**(2026-08-08, ADR-0028).\n   *\n   * 트윈의 구조를 임의의 model 로 덮어쓰는 문이었고, 유일한 소비자는 손저작 편집기였다.\n   * 구조는 원본에서 온다 — 템플릿(`createFromTemplate`)이나 커넥터(`ingestMaster`)가 그 길이다.\n   * 문을 열어 두면 화면만 지워도 다음 소비자가 다시 생긴다.\n   *\n   * 시뮬 트윈을 세우는 것은 여전히 가능하다. 다만 그 입구는 **원본을 만드는 쪽**이지\n   * 트윈을 고치는 쪽이 아니다(ADR-0029 — 시뮬레이터는 원본의 한 종류).\n   */\n\n  /** 기동 — model 를 주면 provision+start, 없으면 레지스트리에 저장된 구조로 start. */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => Boolean, {\n    description: 'Start a twin runtime instance and begin the worker tick. If model is given it provisions first; otherwise it starts from the saved registry model.'\n  })\n  async startTwinInstance(\n    @Arg('instanceId') instanceId: string,\n    @Ctx() context: ResolverContext,\n    @Arg('kind', { nullable: true }) kind?: string,\n    @Arg('model', type => ScalarObject, { nullable: true }) model?: any,\n    /** 새 시뮬레이션은 재기동 때 저널을 이어야 한다. 엔진에는 이미 필수지만 이 API가 누락해\n     * zero-to-twin 경로가 기동 단계에서 막혔다. */\n    @Arg('restartPolicy', { nullable: true }) restartPolicy?: 'resync' | 'resume' | 'reset'\n  ): Promise<boolean> {\n    const domainId = context.state.domain.id\n    // 시각 기준은 **공간**이 갖는다(테넌트 아님) — 교대의 HH:MM 을 어느 기준으로 읽나.\n    if (model) {\n      /* model 를 함께 주는 것은 프로비저닝이다 — 그러면 종류도 말해야 한다.\n         예전에는 `kind ?? 'wms'` 로 메웠는데, 종류를 빠뜨린 야드/생산 트윈이 **창고로 알리지 않고 기동**했다. */\n      if (!kind) throw new Error('kind is required when model is given — it decides which domain kernel runs this twin')\n      TwinEngine.start(instanceId, domainId, kind, await TwinEngine.withSpaceTimeBase(model as TwinModelDef, domainId), restartPolicy)\n    }\n    else await TwinEngine.startFromRegistry(domainId, instanceId)\n    return true\n  }\n\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => Boolean, { description: 'Stop a running twin runtime instance by its id (only if it belongs to the current domain).' })\n  async stopTwinInstance(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<boolean> {\n    if (!TwinEngine.owns(context.state.domain.id, instanceId)) return false // 테넌트 격리 — 남의 도메인 트윈 정지 차단\n    await TwinEngine.stop(context.state.domain.id, instanceId)\n    return true\n  }\n\n  /**\n   * 이 트윈이 **자기 과거를 어떻게 대할 것인가**를 다시 선언한다 (2026-08-20).\n   *\n   * ── 왜 이 문이 필요한가 ────────────────────────────────────────────────────\n   * `restartPolicy` 는 사람이 하는 선언인데, 만들 때 한 번 정하면 **고칠 길이 없었다.** 그래서 「씨앗\n   * 재현용」으로 세운 트윈이 나중에 사람들이 이력을 보는 트윈이 되어도 선언은 `reset` 으로 남았다.\n   * 선언과 쓰임이 어긋난 채로 두면, 선언대로 구현하는 순간(저널 초기화) 이력을 잃는다.\n   *\n   * ── 지금 도는 것에는 손대지 않는다 ─────────────────────────────────────────\n   * 이 값은 **다음 기동**의 규칙이다. 돌고 있는 런타임의 구동 방식을 바꾸려면 정지·기동이 필요하고,\n   * 그 판단은 사람의 것이다(도는 트윈을 알리지 않고 갈아 끼우면 그 사이의 사실이 어디로 갔는지 알 수 없다).\n   * 그래서 결과에 「지금 도는 것과 다르다」는 사실을 함께 낸다.\n   */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => ScalarObject, {\n    description:\n      \"Re-declare how a twin treats its own past on the next boot: 'resync' (re-read from the source), 'resume' (carry its own journal forward) or 'reset' (reproduce from the seed, journal cleared). The value is read strictly — an unknown or legacy word is refused with the accepted words named, because a silent default would decide whether a twin's history survives. This changes the declaration only: a running runtime keeps the mode it was started with, and the result says so (appliesAtNextStart) rather than swapping it underneath.\"\n  })\n  async setTwinRestartPolicy(\n    @Arg('instanceId') instanceId: string,\n    @Arg('restartPolicy') restartPolicy: string,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    const domainId = context.state.domain.id\n    /* 값은 **엄격히** 읽는다 — 모르는 말을 기본값으로 메우면 그 트윈의 이력이 남을지가 알리지 않고 결정된다. */\n    const policy = readRestartPolicy(restartPolicy, `twin \"${instanceId}\"`)\n    const repo = getRepository(TwinInstance)\n    const row = await repo.findOne({ where: { domain: { id: domainId }, instanceId } })\n    if (!row) throw new Error(`unknown twin \"${instanceId}\" in this domain — nothing was changed`)\n\n    const before = row.restartPolicy\n    if (before === policy) return { instanceId, restartPolicy: policy, changed: false, appliesAtNextStart: false }\n\n    await repo.update({ id: row.id }, { restartPolicy: policy })\n    /* 도는 런타임의 구동 방식은 그대로다 — 그 사실을 숨기지 않는다. */\n    const running = !!TwinEngine.metrics(domainId, instanceId)\n    return { instanceId, restartPolicy: policy, previous: before, changed: true, appliesAtNextStart: running }\n  }\n\n  /**\n   * 트윈의 **이름을 다시 붙인다** (2026-08-26).\n   *\n   * ── 왜 이 문이 필요한가 ────────────────────────────────────────────────────\n   * 이름은 트윈을 처음 세울 때 한 번 정해지고(`provision`), 다시 읽기는 그것을 건드리지 않는다. 그\n   * 자체는 안전하다 — 사람이 붙인 이름을 연결이 덮어쓰면 안 된다. 그런데 그래서 **첫날의 이름에\n   * 갇힌다.**\n   *\n   * 실제로 그런 일이 났다: 태양광 발전소를 붙일 때 커넥터가 아는 이름이 연결된 시스템의 코드\n   * (`ES202307202202`)뿐이었다. 뒤에 사람이 부르는 이름(`호현에너지`)이 어디 있는지 알아내 커넥터를\n   * 고쳤는데, 트윈 이름은 그대로였다. **연결된 시스템을 따라가는 트윈에서는 이름이 나중에 좋아진다** —\n   * 커넥터가 나아질 때마다 이 일이 난다.\n   *\n   * 그때 남은 유일한 길이 트윈을 지우고 다시 세우는 것이었다. 그러면 지난 기록이 사라진다 — **이름\n   * 하나 때문에 사실을 버리는 선택**이 된다. 그래서 이름만 바꾸는 문을 낸다.\n   *\n   * ── 연결이 따라오게 하지 않는다 ────────────────────────────────────────────\n   * 다시 읽기가 이름을 따라가게 하면 사람이 붙인 이름을 덮어쓴다. 「사람이 손대지 않았으면 따라간다」가\n   * 옳아 보이지만, 그러려면 「손댔다」는 표시를 새로 만들어야 하고 그것은 이름 하나 때문에 지기에 무거운\n   * 빚이다. 사람이 바꾸는 길만 낸다.\n   *\n   * ── 빈 이름은 받지 않는다 ──────────────────────────────────────────────────\n   * 이름을 지우는 것과 바꾸는 것은 다른 일이다. 빈 값을 받으면 그 트윈은 목록에서 식별자만 남는데,\n   * 그것을 「이름을 바꿨다」로 보고하면 거짓이다. 지우고 싶으면 그 뜻의 문이 따로 있어야 한다.\n   */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => ScalarObject, {\n    description:\n      'Rename a twin instance. The name is set when the twin is first provisioned and a re-read never touches it, ' +\n      'so a twin stays with the name its connector knew on day one — often a code from the connected system. ' +\n      'This changes the name only; nothing about the twin data, its journal or its runtime is affected. ' +\n      'An empty name is refused: clearing a name and changing it are different acts.'\n  })\n  async renameTwinInstance(\n    @Arg('instanceId') instanceId: string,\n    @Arg('name') name: string,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    const domainId = context.state.domain.id\n    const next = String(name ?? '').trim()\n    if (!next) throw new Error(`a twin name cannot be empty — \"${instanceId}\" was left as it was`)\n\n    const repo = getRepository(TwinInstance)\n    const row = await repo.findOne({ where: { domain: { id: domainId }, instanceId } })\n    if (!row) throw new Error(`unknown twin \"${instanceId}\" in this domain — nothing was changed`)\n\n    const before = row.name ?? ''\n    if (before === next) return { instanceId, name: next, changed: false }\n\n    await repo.update({ id: row.id }, { name: next, updater: context.state.user })\n    /* 도는 런타임은 이름을 쓰지 않는다(식별자로 돈다) — 그래서 정지·기동이 필요하지 않다. */\n    return { instanceId, name: next, previous: before || null, changed: true }\n  }\n\n  /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => Boolean, { description: 'Delete a twin instance: stop it, remove the registry entry and purge its event journal.' })\n  async deleteTwinInstance(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<boolean> {\n    await TwinEngine.remove(context.state.domain.id, instanceId)\n    return true\n  }\n\n  /** 관리 목록 — 등록된 인스턴스 전체(kind/status/running/revision/노드·무버 수). 데이터 없으면 빈 배열. */\n  /**\n   * **이 공간의 트윈 id 들** — 한 현실을 여러 렌즈가 비추므로 공간을 물으면 그 렌즈 전부를 답한다.\n   *\n   * 화면이 전체 목록을 받아 걸러 쓰던 규칙을 서버로 모은다. 예측 화면은 같은 확장을 한 파일에서\n   * **두 번** 복제하고 있었고, 규칙이 흩어지면 한쪽만 고쳐진다. 떠 있지 않은 것도 포함한다 —\n   * 공간에 무엇이 있는지는 기동 여부와 다른 사실이다.\n   */\n  @Query(returns => [String], { description: 'Ids of the twins that live in a space (all its lenses), running or not.' })\n  async twinSpaceInstanceIds(@Arg('spaceId') spaceId: string, @Ctx() context: ResolverContext): Promise<string[]> {\n    return TwinEngine.instanceIdsOfSpace(context.state.domain.id, spaceId)\n  }\n\n  @Query(returns => [ScalarObject], {\n    description:\n      'List provisioned twin instances in the current domain with management metadata. Each row also carries `sync`: a one-line answer to \"is this twin keeping in step with the floor?\" — a verdict (syncing | mapping-blocked | no-traffic | not-connected | not-applicable | unknown), the accepted share of the last closed 10-minute window, and up to 36 closed windows of offered/rejected counts for a sparkline. Reasons and rejected-record samples are deliberately absent here; ask twinIngestHealth for one twin when you need them, because carrying raw records for every row would make this list heavy for no gain. acceptedRatio is null while the first window is still filling — a partially filled window under-counts, and drawing it as zero would read as \"nothing passed\".'\n  })\n  async twinInstanceList(@Ctx() context: ResolverContext): Promise<any[]> {\n    const domainId = context.state.domain.id\n    const list = await TwinEngine.list(domainId)\n    /*\n     * 동기화 요약을 **같은 응답에 얹는다.** 따로 질의하면 트윈 수만큼 왕복이 생기고(N+1), 그 사이 화면은\n     * 판정 없는 목록을 먼저 그린다 — 사람이 그 순간을 「정상」으로 읽는다.\n     */\n    const brief = new Map(\n      TwinEngine.ingestHealthBrief(\n        domainId,\n        list.map((x: any) => x.instanceId)\n      ).map(b => [b.instanceId, b])\n    )\n    /*\n     * **쓰기 사실도 같은 응답에 얹는다** (2026-08-20).\n     *\n     * 「이 트윈이 사실을 적고 있나」는 운영자가 트윈 화면에서 묻는 질문인데, 그 답은 벤치(슈퍼유저)의\n     * 부하 계기판에만 있었다. 유입(`sync`)과 나란히 두는 이유는 둘이 한 사슬이기 때문이다 — 받은 것이\n     * 있어도 적히지 않으면 저널이 비고, 그러면 성과·시간여행이 함께 빈다.\n     *\n     * 계기는 메모리라 왕복이 없다. **도는 트윈만** 답이 있고, 멈춘 트윈은 `null` 이다(0 이 아니다 —\n     * 「쓰지 않았다」와 「돌지 않는다」는 다른 사실이다).\n     */\n    return list.map((x: any) => {\n      const m = TwinEngine.metrics(domainId, x.instanceId)\n      return {\n        ...x,\n        sync: brief.get(x.instanceId) ?? null,\n        write: m ? { rate: m.journalRate, journaled: m.journaledTotal, backlog: m.backlog } : null\n      }\n    })\n  }\n\n  /** 단건 상세 — 프로비저닝 에디터용 model(구조+layout) 포함. */\n  @Query(returns => ScalarObject, { nullable: true, description: 'Get one provisioned twin instance with its TwinModelDef (structure + layout) for editing.' })\n  async twinInstanceDetail(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any | null> {\n    return TwinEngine.detail(context.state.domain.id, instanceId)\n  }\n\n  /**\n   * 라이브(메모리) 인스턴스 id 목록 — 콘솔 셀렉터·포트폴리오용. **현재 도메인만**(테넌트 격리).\n   * 과거엔 Object.keys(TwinEngine.instances) 로 전역 반환 → 다른 도메인 트윈이 종합현황/셀렉터에 새던 버그.\n   * 도메인 스코프 목록(twinInstanceList 와 동일 소스)에서 running 만 추린다.\n   */\n  @Query(returns => [String], { description: 'List ids of running (in-memory) twin runtime instances in the current domain (tenant-isolated).' })\n  async twinInstances(@Ctx() context: ResolverContext): Promise<string[]> {\n    const list = await TwinEngine.list(context.state.domain.id)\n    return list.filter((x: any) => x.running).map((x: any) => x.instanceId)\n  }\n\n  /**\n   * 도메인 어휘 카탈로그 — 커널(레퍼런스) SSOT 를 그대로 노출. { wms:{label,locationTypes[]}, yms:…, mes:… }.\n   * 프로비저닝 UI 는 이걸 소싱해 노드 타입/시스템을 채운다(앱 내 하드코딩 금지).\n   */\n  @Query(returns => ScalarObject, { description: 'Domain vocabulary catalog (per-system location location types) sourced from the twin kernel — SSOT for provisioning UI.' })\n  twinDomainCatalog(): any {\n    return domainCatalog()\n  }\n}\n"]}
+{"version":3,"file":"twin-lifecycle-mutation.js","sourceRoot":"","sources":["../../../server/service/twin-lifecycle/twin-lifecycle-mutation.ts"],"names":[],"mappings":"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","sourcesContent":["import { Arg, Ctx, Mutation, Query, Resolver, Directive} from 'type-graphql'\n\nimport { ScalarObject, getRepository } from '@things-factory/shell'\n\nimport { TwinEngine } from '../../engine/index.js'\n/* 정책 읽기는 그 모듈에서 직접 가져온다 — 다른 소비처(`reference-resolver`)와 같은 길이다. */\nimport { readRestartPolicy } from '../../engine/restart-policy.js'\nimport { TwinInstance } from '../twin-instance/twin-instance.js'\nimport { TwinEvent } from '../twin-event/twin-event.js'\n\nimport type { TwinModelDef } from '@operato/ops-contract'\n\n/* 도메인 어휘 카탈로그(시스템별 노드 타입) — 커널이 SSOT. 앱/UI 는 이걸 소싱하고 재선언하지 않는다(방언 금지).\n * 조합은 domain-catalog.ts 가 소유 — 리졸버와 서버측 소비자(board-ai 도구 등)가 같은 형태를 본다. */\nimport { domainCatalog } from './domain-catalog.js'\n\n/*\n * 트윈 인스턴스 생명주기 채널 — 프로비저닝(상향, ADR-0015).\n * State/Command/Scenario 는 이미 running 인 인스턴스를 다루지만, 이 채널은 인스턴스 자체를 만들고/설정하고/없앤다.\n * 생명주기: provision(save, 미기동) → start → stop → delete. 모두 domain 스코프(context.state.domain.id).\n * model(TwinModelDef+layout)=구조, scenario=자극 은 분리 — 여기선 구조만 세운다. 자극은 **원본이 선언하고**\n * (`TwinReference.connectionConfig.scenario`) 기동이 싣거나, 원본의 구동 능력으로 태운다(ADR-0029 §4·§8).\n */\n@Resolver()\nexport class TwinLifecycleMutation {\n  /*\n   * `saveTwinInstance` 는 **없앴다**(2026-08-08, ADR-0028).\n   *\n   * 트윈의 구조를 임의의 model 로 덮어쓰는 문이었고, 유일한 소비자는 손저작 편집기였다.\n   * 구조는 원본에서 온다 — 템플릿(`createFromTemplate`)이나 커넥터(`ingestMaster`)가 그 길이다.\n   * 문을 열어 두면 화면만 지워도 다음 소비자가 다시 생긴다.\n   *\n   * 시뮬 트윈을 세우는 것은 여전히 가능하다. 다만 그 입구는 **원본을 만드는 쪽**이지\n   * 트윈을 고치는 쪽이 아니다(ADR-0029 — 시뮬레이터는 원본의 한 종류).\n   */\n\n  /** 기동 — model 를 주면 provision+start, 없으면 레지스트리에 저장된 구조로 start. */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => Boolean, {\n    description: 'Start a twin runtime instance and begin the worker tick. If model is given it provisions first; otherwise it starts from the saved registry model.'\n  })\n  async startTwinInstance(\n    @Arg('instanceId') instanceId: string,\n    @Ctx() context: ResolverContext,\n    @Arg('kind', { nullable: true }) kind?: string,\n    @Arg('model', type => ScalarObject, { nullable: true }) model?: any,\n    /** 새 시뮬레이션은 재기동 때 저널을 이어야 한다. 엔진에는 이미 필수지만 이 API가 누락해\n     * zero-to-twin 경로가 기동 단계에서 막혔다. */\n    @Arg('restartPolicy', { nullable: true }) restartPolicy?: 'resync' | 'resume' | 'reset'\n  ): Promise<boolean> {\n    const domainId = context.state.domain.id\n    // 시각 기준은 **공간**이 갖는다(테넌트 아님) — 교대의 HH:MM 을 어느 기준으로 읽나.\n    if (model) {\n      /* model 를 함께 주는 것은 프로비저닝이다 — 그러면 종류도 말해야 한다.\n         예전에는 `kind ?? 'wms'` 로 메웠는데, 종류를 빠뜨린 야드/생산 트윈이 **창고로 알리지 않고 기동**했다. */\n      if (!kind) throw new Error('kind is required when model is given — it decides which domain kernel runs this twin')\n      TwinEngine.start(instanceId, domainId, kind, await TwinEngine.withSpaceTimeBase(model as TwinModelDef, domainId), restartPolicy)\n    }\n    else await TwinEngine.startFromRegistry(domainId, instanceId)\n    return true\n  }\n\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => Boolean, { description: 'Stop a running twin runtime instance by its id (only if it belongs to the current domain).' })\n  async stopTwinInstance(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<boolean> {\n    if (!TwinEngine.owns(context.state.domain.id, instanceId)) return false // 테넌트 격리 — 남의 도메인 트윈 정지 차단\n    await TwinEngine.stop(context.state.domain.id, instanceId)\n    return true\n  }\n\n  /**\n   * 이 트윈이 **자기 과거를 어떻게 대할 것인가**를 다시 선언한다 (2026-08-20).\n   *\n   * ── 왜 이 문이 필요한가 ────────────────────────────────────────────────────\n   * `restartPolicy` 는 사람이 하는 선언인데, 만들 때 한 번 정하면 **고칠 길이 없었다.** 그래서 「씨앗\n   * 재현용」으로 세운 트윈이 나중에 사람들이 이력을 보는 트윈이 되어도 선언은 `reset` 으로 남았다.\n   * 선언과 쓰임이 어긋난 채로 두면, 선언대로 구현하는 순간(저널 초기화) 이력을 잃는다.\n   *\n   * ── 지금 도는 것에는 손대지 않는다 ─────────────────────────────────────────\n   * 이 값은 **다음 기동**의 규칙이다. 돌고 있는 런타임의 구동 방식을 바꾸려면 정지·기동이 필요하고,\n   * 그 판단은 사람의 것이다(도는 트윈을 알리지 않고 갈아 끼우면 그 사이의 사실이 어디로 갔는지 알 수 없다).\n   * 그래서 결과에 「지금 도는 것과 다르다」는 사실을 함께 낸다.\n   */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => ScalarObject, {\n    description:\n      \"Re-declare how a twin treats its own past on the next boot: 'resync' (re-read from the source), 'resume' (carry its own journal forward) or 'reset' (reproduce from the seed, journal cleared). The value is read strictly — an unknown or legacy word is refused with the accepted words named, because a silent default would decide whether a twin's history survives. This changes the declaration only: a running runtime keeps the mode it was started with, and the result says so (appliesAtNextStart) rather than swapping it underneath.\"\n  })\n  async setTwinRestartPolicy(\n    @Arg('instanceId') instanceId: string,\n    @Arg('restartPolicy') restartPolicy: string,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    const domainId = context.state.domain.id\n    /* 값은 **엄격히** 읽는다 — 모르는 말을 기본값으로 메우면 그 트윈의 이력이 남을지가 알리지 않고 결정된다. */\n    const policy = readRestartPolicy(restartPolicy, `twin \"${instanceId}\"`)\n    const repo = getRepository(TwinInstance)\n    const row = await repo.findOne({ where: { domain: { id: domainId }, instanceId } })\n    if (!row) throw new Error(`unknown twin \"${instanceId}\" in this domain — nothing was changed`)\n\n    const before = row.restartPolicy\n    if (before === policy) return { instanceId, restartPolicy: policy, changed: false, appliesAtNextStart: false }\n\n    await repo.update({ id: row.id }, { restartPolicy: policy })\n    /* 도는 런타임의 구동 방식은 그대로다 — 그 사실을 숨기지 않는다. */\n    const running = !!TwinEngine.metrics(domainId, instanceId)\n    return { instanceId, restartPolicy: policy, previous: before, changed: true, appliesAtNextStart: running }\n  }\n\n  /**\n   * 트윈의 **이름을 다시 붙인다** (2026-08-26).\n   *\n   * ── 왜 이 문이 필요한가 ────────────────────────────────────────────────────\n   * 이름은 트윈을 처음 세울 때 한 번 정해지고(`provision`), 다시 읽기는 그것을 건드리지 않는다. 그\n   * 자체는 안전하다 — 사람이 붙인 이름을 연결이 덮어쓰면 안 된다. 그런데 그래서 **첫날의 이름에\n   * 갇힌다.**\n   *\n   * 실제로 그런 일이 났다: 태양광 발전소를 붙일 때 커넥터가 아는 이름이 연결된 시스템의 코드\n   * (`ES202307202202`)뿐이었다. 뒤에 사람이 부르는 이름(`호현에너지`)이 어디 있는지 알아내 커넥터를\n   * 고쳤는데, 트윈 이름은 그대로였다. **연결된 시스템을 따라가는 트윈에서는 이름이 나중에 좋아진다** —\n   * 커넥터가 나아질 때마다 이 일이 난다.\n   *\n   * 그때 남은 유일한 길이 트윈을 지우고 다시 세우는 것이었다. 그러면 지난 기록이 사라진다 — **이름\n   * 하나 때문에 사실을 버리는 선택**이 된다. 그래서 이름만 바꾸는 문을 낸다.\n   *\n   * ── 연결이 따라오게 하지 않는다 ────────────────────────────────────────────\n   * 다시 읽기가 이름을 따라가게 하면 사람이 붙인 이름을 덮어쓴다. 「사람이 손대지 않았으면 따라간다」가\n   * 옳아 보이지만, 그러려면 「손댔다」는 표시를 새로 만들어야 하고 그것은 이름 하나 때문에 지기에 무거운\n   * 빚이다. 사람이 바꾸는 길만 낸다.\n   *\n   * ── 빈 이름은 받지 않는다 ──────────────────────────────────────────────────\n   * 이름을 지우는 것과 바꾸는 것은 다른 일이다. 빈 값을 받으면 그 트윈은 목록에서 식별자만 남는데,\n   * 그것을 「이름을 바꿨다」로 보고하면 거짓이다. 지우고 싶으면 그 뜻의 문이 따로 있어야 한다.\n   */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => ScalarObject, {\n    description:\n      'Rename a twin instance. The name is set when the twin is first provisioned and a re-read never touches it, ' +\n      'so a twin stays with the name its connector knew on day one — often a code from the connected system. ' +\n      'This changes the name only; nothing about the twin data, its journal or its runtime is affected. ' +\n      'An empty name is refused: clearing a name and changing it are different acts.'\n  })\n  async renameTwinInstance(\n    @Arg('instanceId') instanceId: string,\n    @Arg('name') name: string,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    const domainId = context.state.domain.id\n    const next = String(name ?? '').trim()\n    if (!next) throw new Error(`a twin name cannot be empty — \"${instanceId}\" was left as it was`)\n\n    const repo = getRepository(TwinInstance)\n    const row = await repo.findOne({ where: { domain: { id: domainId }, instanceId } })\n    if (!row) throw new Error(`unknown twin \"${instanceId}\" in this domain — nothing was changed`)\n\n    const before = row.name ?? ''\n    if (before === next) return { instanceId, name: next, changed: false }\n\n    await repo.update({ id: row.id }, { name: next, updater: context.state.user })\n    /* 도는 런타임은 이름을 쓰지 않는다(식별자로 돈다) — 그래서 정지·기동이 필요하지 않다. */\n    return { instanceId, name: next, previous: before || null, changed: true }\n  }\n\n  /**\n   * 폐기 전에 사라질 것을 읽는다.\n   *\n   * 삭제는 레지스트리 행 하나만 없애는 일이 아니다. `TwinEngine.remove` 는 같은 트윈의 저널도\n   * purge 한다. 그래서 확인 창이 추측한 숫자를 쓰지 않고, **삭제와 같은 domain·instance 범위**를\n   * 직접 센다. 저널이 비어 있는 트윈도 `0` 과 null 기간을 돌려준다 — 없는 기록을 기간으로\n   * 꾸며내면 \"아무것도 안 지워진다\"와 \"언제부터인지 모른다\"가 섞인다.\n   */\n  @Query(returns => ScalarObject, {\n    nullable: true,\n    description:\n      'Describe what deleting one twin would purge before it is deleted: its registry identity and the count plus first/last event time of its journal. Null means this twin is not in the current domain.'\n  })\n  async twinDeletionPreview(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any | null> {\n    const domainId = context.state.domain.id\n    const instance = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })\n\n    if (!instance) return null\n\n    const journal = await getRepository(TwinEvent)\n      .createQueryBuilder('event')\n      .select('COUNT(event.id)', 'count')\n      .addSelect('MIN(event.eventTime)', 'firstEventAt')\n      .addSelect('MAX(event.eventTime)', 'lastEventAt')\n      .where('event.domain = :domainId', { domainId })\n      .andWhere('event.instanceId = :instanceId', { instanceId })\n      .getRawOne<{ count?: string | number; firstEventAt?: unknown; lastEventAt?: unknown }>()\n\n    return {\n      instanceId,\n      name: instance.name ?? null,\n      journalCount: Number(journal?.count ?? 0),\n      firstEventAt: journal?.firstEventAt ?? null,\n      lastEventAt: journal?.lastEventAt ?? null\n    }\n  }\n\n  /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => Boolean, { description: 'Delete a twin instance: stop it, remove the registry entry and purge its event journal.' })\n  async deleteTwinInstance(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<boolean> {\n    await TwinEngine.remove(context.state.domain.id, instanceId)\n    return true\n  }\n\n  /** 관리 목록 — 등록된 인스턴스 전체(kind/status/running/revision/노드·무버 수). 데이터 없으면 빈 배열. */\n  /**\n   * **이 공간의 트윈 id 들** — 한 현실을 여러 렌즈가 비추므로 공간을 물으면 그 렌즈 전부를 답한다.\n   *\n   * 화면이 전체 목록을 받아 걸러 쓰던 규칙을 서버로 모은다. 예측 화면은 같은 확장을 한 파일에서\n   * **두 번** 복제하고 있었고, 규칙이 흩어지면 한쪽만 고쳐진다. 떠 있지 않은 것도 포함한다 —\n   * 공간에 무엇이 있는지는 기동 여부와 다른 사실이다.\n   */\n  @Query(returns => [String], { description: 'Ids of the twins that live in a space (all its lenses), running or not.' })\n  async twinSpaceInstanceIds(@Arg('spaceId') spaceId: string, @Ctx() context: ResolverContext): Promise<string[]> {\n    return TwinEngine.instanceIdsOfSpace(context.state.domain.id, spaceId)\n  }\n\n  @Query(returns => [ScalarObject], {\n    description:\n      'List provisioned twin instances in the current domain with management metadata. Each row also carries `sync`: a one-line answer to \"is this twin keeping in step with the floor?\" — a verdict (syncing | mapping-blocked | no-traffic | not-connected | not-applicable | unknown), the accepted share of the last closed 10-minute window, and up to 36 closed windows of offered/rejected counts for a sparkline. Reasons and rejected-record samples are deliberately absent here; ask twinIngestHealth for one twin when you need them, because carrying raw records for every row would make this list heavy for no gain. acceptedRatio is null while the first window is still filling — a partially filled window under-counts, and drawing it as zero would read as \"nothing passed\".'\n  })\n  async twinInstanceList(@Ctx() context: ResolverContext): Promise<any[]> {\n    const domainId = context.state.domain.id\n    const list = await TwinEngine.list(domainId)\n    /*\n     * 동기화 요약을 **같은 응답에 얹는다.** 따로 질의하면 트윈 수만큼 왕복이 생기고(N+1), 그 사이 화면은\n     * 판정 없는 목록을 먼저 그린다 — 사람이 그 순간을 「정상」으로 읽는다.\n     */\n    const brief = new Map(\n      TwinEngine.ingestHealthBrief(\n        domainId,\n        list.map((x: any) => x.instanceId)\n      ).map(b => [b.instanceId, b])\n    )\n    /*\n     * **쓰기 사실도 같은 응답에 얹는다** (2026-08-20).\n     *\n     * 「이 트윈이 사실을 적고 있나」는 운영자가 트윈 화면에서 묻는 질문인데, 그 답은 벤치(슈퍼유저)의\n     * 부하 계기판에만 있었다. 유입(`sync`)과 나란히 두는 이유는 둘이 한 사슬이기 때문이다 — 받은 것이\n     * 있어도 적히지 않으면 저널이 비고, 그러면 성과·시간여행이 함께 빈다.\n     *\n     * 계기는 메모리라 왕복이 없다. **도는 트윈만** 답이 있고, 멈춘 트윈은 `null` 이다(0 이 아니다 —\n     * 「쓰지 않았다」와 「돌지 않는다」는 다른 사실이다).\n     */\n    return list.map((x: any) => {\n      const m = TwinEngine.metrics(domainId, x.instanceId)\n      return {\n        ...x,\n        sync: brief.get(x.instanceId) ?? null,\n        write: m ? { rate: m.journalRate, journaled: m.journaledTotal, backlog: m.backlog } : null\n      }\n    })\n  }\n\n  /** 단건 상세 — 프로비저닝 에디터용 model(구조+layout) 포함. */\n  @Query(returns => ScalarObject, { nullable: true, description: 'Get one provisioned twin instance with its TwinModelDef (structure + layout) for editing.' })\n  async twinInstanceDetail(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any | null> {\n    return TwinEngine.detail(context.state.domain.id, instanceId)\n  }\n\n  /**\n   * 라이브(메모리) 인스턴스 id 목록 — 콘솔 셀렉터·포트폴리오용. **현재 도메인만**(테넌트 격리).\n   * 과거엔 Object.keys(TwinEngine.instances) 로 전역 반환 → 다른 도메인 트윈이 종합현황/셀렉터에 새던 버그.\n   * 도메인 스코프 목록(twinInstanceList 와 동일 소스)에서 running 만 추린다.\n   */\n  @Query(returns => [String], { description: 'List ids of running (in-memory) twin runtime instances in the current domain (tenant-isolated).' })\n  async twinInstances(@Ctx() context: ResolverContext): Promise<string[]> {\n    const list = await TwinEngine.list(context.state.domain.id)\n    return list.filter((x: any) => x.running).map((x: any) => x.instanceId)\n  }\n\n  /**\n   * 도메인 어휘 카탈로그 — 커널(레퍼런스) SSOT 를 그대로 노출. { wms:{label,locationTypes[]}, yms:…, mes:… }.\n   * 프로비저닝 UI 는 이걸 소싱해 노드 타입/시스템을 채운다(앱 내 하드코딩 금지).\n   */\n  @Query(returns => ScalarObject, { description: 'Domain vocabulary catalog (per-system location location types) sourced from the twin kernel — SSOT for provisioning UI.' })\n  twinDomainCatalog(): any {\n    return domainCatalog()\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/headless-twin",
-  "version": "10.1.8",
+  "version": "10.1.11",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh <heartyoh@hatiolab.com>",
@@ -27,13 +27,13 @@
     "clean:shared": "rm -rf dist-shared tsconfig.shared.tsbuildinfo"
   },
   "dependencies": {
-    "@operato/ops-contract": "^0.9.17",
-    "@operato/twin-kernel": "^0.11.10",
+    "@operato/ops-contract": "^0.9.19",
+    "@operato/twin-kernel": "^0.11.11",
     "@things-factory/auth-base": "^10.1.7",
     "@things-factory/cache-service": "^10.1.7",
     "@things-factory/env": "^10.1.3",
     "@things-factory/ingest": "^10.1.7",
     "@things-factory/shell": "^10.1.7"
   },
-  "gitHead": "c402982e29aab3b49e56bea4e41948be6a749c7f"
+  "gitHead": "3079d77730de84c80f8ac2ed8343d6f624a94ed2"
 }

package/server/migrations/1786800000000-CreateTwinReferenceReconciliations.ts

@@ -0,0 +1,39 @@
+import { MigrationInterface, QueryRunner, Table, TableIndex } from 'typeorm'
+
+/* 번호 대사는 원본 범위를 실제로 읽은 뒤의 최신 상태를 재기동 뒤에도 보존한다. */
+const TABLE = 'twin_reference_reconciliations'
+
+export class CreateTwinReferenceReconciliations1786800000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    if (await queryRunner.hasTable(TABLE)) return
+    const dateType = queryRunner.connection.driver.mappedDataTypes.createDate as string
+    await queryRunner.createTable(new Table({
+      name: TABLE,
+      columns: [
+        { name: 'id', type: 'varchar', length: '36', isPrimary: true },
+        { name: 'domain_id', type: 'varchar', length: '36', isNullable: true },
+        { name: 'instance_id', type: 'varchar', isNullable: false },
+        { name: 'scope', type: 'varchar', isNullable: false },
+        { name: 'status', type: 'varchar', isNullable: false },
+        { name: 'source_first', type: 'int', isNullable: true },
+        { name: 'source_last', type: 'int', isNullable: true },
+        { name: 'cursor_seq', type: 'int', isNullable: true },
+        { name: 'first_seq_seen', type: 'int', isNullable: true },
+        { name: 'head_missing', type: 'int', isNullable: true },
+        { name: 'behind', type: 'int', isNullable: true },
+        { name: 'reason', type: 'varchar', isNullable: true },
+        { name: 'checked_at', type: dateType, isNullable: false },
+        { name: 'created_at', type: dateType, isNullable: true },
+        { name: 'updated_at', type: dateType, isNullable: true }
+      ]
+    }), true)
+    const table = await queryRunner.getTable(TABLE)
+    if (!table) return
+    await queryRunner.createIndex(table, new TableIndex({ name: 'uq_twin_reference_reconciliation_0', columnNames: ['domain_id', 'instance_id', 'scope'], isUnique: true }))
+    await queryRunner.createIndex(table, new TableIndex({ name: 'ix_twin_reference_reconciliation_0', columnNames: ['domain_id', 'instance_id', 'checked_at'] }))
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    if (await queryRunner.hasTable(TABLE)) await queryRunner.dropTable(TABLE)
+  }
+}

package/server/migrations/index.ts

@@ -9,6 +9,7 @@ import { IndexEventTypeByTime1786300000000 } from './1786300000000-IndexEventTyp
 import { IndexEventCreatedAt1786400000000 } from './1786400000000-IndexEventCreatedAt.js'
 import { CreateTwinSubjectEvents1786500000000 } from './1786500000000-CreateTwinSubjectEvents.js'
 import { AddDispatchRetryColumns1786700000000 } from './1786700000000-AddDispatchRetryColumns.js'
+import { CreateTwinReferenceReconciliations1786800000000 } from './1786800000000-CreateTwinReferenceReconciliations.js'
 import { RenameOperatoMesAdapterType1786600000000 } from './1786600000000-RenameOperatoMesAdapterType.js'
 
 export const migrations = [
@@ -19,5 +20,6 @@ export const migrations = [
   IndexEventCreatedAt1786400000000,
   CreateTwinSubjectEvents1786500000000,
   RenameOperatoMesAdapterType1786600000000,
-  AddDispatchRetryColumns1786700000000
+  AddDispatchRetryColumns1786700000000,
+  CreateTwinReferenceReconciliations1786800000000
 ]

package/server/service/index.ts

@@ -15,6 +15,8 @@ export * from './reference/reference-adapter.js'
 export * from './reference/live-cadence.js'
 export * from './reference/reference-live.js'
 export * from './reference/twin-reference.js'
+export * from './reference/twin-reference-reconciliation.js'
+export * from './reference/reference-reconciliation.js'
 export * from './reference/connection-portability.js'
 export * from './reference/template-registry.js'
 /* 커넥터 점검 하네스 — 실 원본에 붙여 무엇이 채워지고 무엇이 비는지 센다(앱을 띄우지 않는다). */

package/server/service/reference/index.ts

@@ -2,9 +2,11 @@ import { ConnectionPortabilityResolver } from './connection-portability-resolver
 import { TwinReferenceResolver } from './reference-resolver.js'
 import { TwinReferenceProgressSubscription } from './reference-progress-subscription.js'
 import { TwinReference } from './twin-reference.js'
+import { TwinReferenceReconciliation } from './twin-reference-reconciliation.js'
+import { TwinReferenceReconciliationQuery } from './reference-reconciliation-query.js'
 
-export const entities = [TwinReference]
-export const resolvers = [TwinReferenceResolver, TwinReferenceProgressSubscription, ConnectionPortabilityResolver]
+export const entities = [TwinReference, TwinReferenceReconciliation]
+export const resolvers = [TwinReferenceResolver, TwinReferenceProgressSubscription, ConnectionPortabilityResolver, TwinReferenceReconciliationQuery]
 export * from './control-routing.js'
 /* 진행 단계 어휘 — **모든 커넥터가 같은 낱말로 말한다.** 화면은 단계마다 번역 하나만 두면 된다. */
 export * from './reference-progress.js'
@@ -12,4 +14,5 @@ export * from './reference-progress.js'
 export * from './reference-probe.js'
 /* 놓친 구간을 backfill 해 채우는 길 — 밀어 받는 길과 같은 번호 검사를 지난다. */
 export * from './reference-fill.js'
+export * from './reference-reconciliation.js'
 export * from './connection-portability.js'

package/server/service/reference/reference-fill-run.ts

@@ -28,9 +28,10 @@ import { getRepository } from '@things-factory/shell'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinReference } from './twin-reference.js'
 import { getAdapter, type SeqReport, type SiteDescriptor } from './reference-adapter.js'
-import { pushCursorKey, withSeq } from './hook-contract.js'
+import { firstSeqOf, pushCursorKey, seqOf, withSeq } from './hook-contract.js'
 import { fillSince, type FillOutcome } from './reference-fill.js'
 import { liveIngest } from './live-ingest.js'
+import { recordReferenceReconciliation } from './reference-reconciliation-writer.js'
 import { journalIdentities, spanOf } from './fill-dedupe.js'
 import { TwinEngine } from '../../engine/index.js'
 import { twinLog, twinWarn } from '../../engine/log.js'
@@ -87,6 +88,8 @@ export async function runFill(args: {
    * 가 나아간 만큼만 적으므로, 잃은 구간을 되찾은 뒤 커서는 원래 자리보다 앞서지 않습니다.
    */
   const cursor = from === undefined ? ((ref as any).liveCursor ?? {}) : withSeq((ref as any).liveCursor, cursorKey, from)
+  /* fillSince가 커서를 저장할 때 이 지역 값도 같이 바꾼다. 저장본을 다시 읽어 대사를 늦추지 않는다. */
+  let persistedCursor: unknown = cursor
 
   const outcome = await fillSince({
     cfg: ref.connectionConfig ?? {},
@@ -119,10 +122,21 @@ export async function runFill(args: {
     },
     saveCursor: async next => {
       await repo.update({ id: (ref as any).id }, { liveCursor: next } as any)
+      persistedCursor = next
     },
     ...(maxPages ? { maxPages } : {})
   })
 
+  /* 원본이 실제로 답한 범위가 있을 때만 기록한다. 범위를 모르는 것은 "정상"으로 덮지 않는다. */
+  await recordReferenceReconciliation({
+    domainId,
+    instanceId,
+    scope,
+    sourceRange: outcome.sourceRange,
+    cursorSeq: seqOf(persistedCursor, cursorKey),
+    firstSeqSeen: firstSeqOf(persistedCursor, cursorKey)
+  }).catch(err => twinWarn(`[twin-reconcile] "${instanceId}" · ${scope} 상태를 적지 못했습니다: ${err?.message ?? err}`))
+
   const say = `[twin-fill] "${instanceId}" · ${scope} — ${outcome.applied}건 넣음 · ${outcome.pages}쪽 · ${outcome.stopped}${outcome.detail ? ` (${outcome.detail})` : ''}`
   /* 끝난 것과 막힌 것을 다른 소리로 남깁니다 — 구멍은 사람이 원본을 봐야 합니다. */
   if (outcome.stopped === 'done' || outcome.stopped === 'no-progress') twinLog(say)

package/server/service/reference/reference-reconciliation-query.ts

@@ -0,0 +1,28 @@
+import { Arg, Ctx, Query, Resolver } from 'type-graphql'
+import { getRepository } from '@things-factory/shell'
+import { TwinReferenceReconciliation } from './twin-reference-reconciliation.js'
+
+@Resolver()
+export class TwinReferenceReconciliationQuery {
+  @Query(returns => [TwinReferenceReconciliation], { description: 'All latest durable sequence reconciliations for one Twin. An empty list means no numbered source range has been read yet, not that every source is aligned.' })
+  async twinReferenceReconciliations(
+    @Arg('instanceId') instanceId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<TwinReferenceReconciliation[]> {
+    return getRepository(TwinReferenceReconciliation).find({
+      where: { domain: { id: context.state.domain.id }, instanceId },
+      order: { scope: 'ASC' }
+    })
+  }
+
+  @Query(returns => TwinReferenceReconciliation, { nullable: true, description: 'Latest durable source-range versus Twin-cursor reconciliation for one numbered scope. Null means no backfill has yet obtained a source range; it is not an aligned result.' })
+  async twinReferenceReconciliation(
+    @Arg('instanceId') instanceId: string,
+    @Arg('scope') scope: string,
+    @Ctx() context: ResolverContext
+  ): Promise<TwinReferenceReconciliation | null> {
+    return getRepository(TwinReferenceReconciliation).findOne({
+      where: { domain: { id: context.state.domain.id }, instanceId, scope }
+    })
+  }
+}

package/server/service/reference/reference-reconciliation-writer.ts

@@ -0,0 +1,38 @@
+import { getRepository } from '@things-factory/shell'
+import { TwinReferenceReconciliation } from './twin-reference-reconciliation.js'
+import { reconcileReferenceSequence, type ReferenceRange } from './reference-reconciliation.js'
+
+/** backfill이 원본 범위를 실제로 읽은 뒤에만 최신 대사 상태를 갱신한다. */
+export async function recordReferenceReconciliation(args: {
+  domainId: string
+  instanceId: string
+  scope: string
+  sourceRange?: ReferenceRange
+  cursorSeq?: number
+  firstSeqSeen?: number
+}): Promise<void> {
+  const { domainId, instanceId, scope, sourceRange, cursorSeq, firstSeqSeen } = args
+  if (!sourceRange) return
+  const verdict = reconcileReferenceSequence({ source: sourceRange, cursorSeq, firstSeqSeen })
+  const repo = getRepository(TwinReferenceReconciliation)
+  const previous = await repo.findOne({ where: { domain: { id: domainId }, instanceId, scope } })
+  await repo.save(
+    repo.create({
+      ...(previous ?? {}),
+      domain: { id: domainId } as any,
+      instanceId,
+      scope,
+      status: verdict.status,
+      /* TypeORM은 undefined를 "갱신하지 않음"으로 읽는다. 현재 대사가 맞아진 뒤 옛 gap 수가
+       * 남지 않게 nullable 칸은 명시적으로 null로 지운다. */
+      sourceFirst: verdict.sourceFirst ?? null,
+      sourceLast: verdict.sourceLast ?? null,
+      cursorSeq: verdict.cursorSeq ?? null,
+      firstSeqSeen: verdict.firstSeqSeen ?? null,
+      headMissing: verdict.headMissing ?? null,
+      behind: verdict.behind ?? null,
+      reason: verdict.reason ?? null,
+      checkedAt: new Date()
+    })
+  )
+}

package/server/service/reference/reference-reconciliation.ts

@@ -0,0 +1,55 @@
+/*
+ * 원본 번호 범위와 Twin 커서를 맞춘 **현재 판정**이다.
+ *
+ * 이 계산은 봉투 수와 저널 행 수를 비교하지 않는다. 재전송과 backfill 때문에 그 둘은 같은
+ * 사실을 여러 번 셀 수 있다. 여기서 답하는 것은 번호를 매기는 원본에서만 가능한, 더 좁고
+ * 검증 가능한 질문이다: "원본의 양 끝과 우리가 처음/마지막으로 받은 번호가 이어지는가?"
+ */
+export type ReferenceRange = { first?: number; last?: number }
+
+export type ReferenceReconciliation = {
+  sourceFirst?: number
+  sourceLast?: number
+  cursorSeq?: number
+  firstSeqSeen?: number
+  headMissing?: number
+  behind?: number
+  status: 'aligned' | 'gap' | 'unknown'
+  reason?: string
+}
+
+export function reconcileReferenceSequence(args: {
+  source: ReferenceRange | undefined
+  cursorSeq?: number
+  firstSeqSeen?: number
+}): ReferenceReconciliation {
+  const { source, cursorSeq, firstSeqSeen } = args
+  const sourceFirst = source?.first
+  const sourceLast = source?.last
+  const base = { sourceFirst, sourceLast, cursorSeq, firstSeqSeen }
+
+  if (sourceFirst === undefined || sourceLast === undefined) {
+    return { ...base, status: 'unknown', reason: '원본이 번호 범위의 양 끝을 주지 않아 대사할 수 없습니다' }
+  }
+  if (cursorSeq === undefined) {
+    return { ...base, status: 'unknown', reason: 'Twin이 아직 이 단위의 번호를 받은 적이 없습니다' }
+  }
+  if (cursorSeq < sourceFirst) {
+    return {
+      ...base,
+      status: 'unknown',
+      reason: 'Twin 커서가 원본의 첫 번호보다 앞입니다. 원본 번호가 다시 매겨졌거나 다른 단위의 커서입니다'
+    }
+  }
+
+  const behind = Math.max(0, sourceLast - cursorSeq)
+  /* 처음 받은 번호를 적지 않았으면 앞머리는 "없음"이 아니라 "모름"이다. */
+  const headMissing = firstSeqSeen === undefined ? undefined : Math.max(0, firstSeqSeen - sourceFirst)
+  if (behind || headMissing) {
+    return { ...base, ...(behind ? { behind } : {}), ...(headMissing ? { headMissing } : {}), status: 'gap' }
+  }
+  if (firstSeqSeen === undefined) {
+    return { ...base, status: 'unknown', reason: '처음 받은 번호가 기록되지 않아 앞머리 연속성은 확인할 수 없습니다' }
+  }
+  return { ...base, status: 'aligned' }
+}

package/server/service/reference/twin-reference-reconciliation.ts

@@ -0,0 +1,27 @@
+import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId, UpdateDateColumn } from 'typeorm'
+import { Field, ID, Int, ObjectType } from 'type-graphql'
+import { Domain } from '@things-factory/shell'
+
+/* 한 연결·Twin·단위의 최신 번호 대사 상태. 과거 추이는 ingest window가, 현재 조치 판단은 이 표가 답한다. */
+@Entity()
+@Index('uq_twin_reference_reconciliation_0', (e: TwinReferenceReconciliation) => [e.domain, e.instanceId, e.scope], { unique: true })
+@Index('ix_twin_reference_reconciliation_0', (e: TwinReferenceReconciliation) => [e.domain, e.instanceId, e.checkedAt], { unique: false })
+@ObjectType({ description: 'Latest durable sequence reconciliation for one connected source scope. It reports only what numbered source ranges can prove; it never substitutes replay-prone ingest-window counts for source facts.' })
+export class TwinReferenceReconciliation {
+  @PrimaryGeneratedColumn('uuid') @Field(type => ID) readonly id: string
+  @ManyToOne(type => Domain) @Field(type => Domain, { nullable: true }) domain?: Domain
+  @RelationId((e: TwinReferenceReconciliation) => e.domain) domainId?: string
+  @Column() @Field() instanceId: string
+  @Column() @Field() scope: string
+  @Column() @Field() status: 'aligned' | 'gap' | 'unknown'
+  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) sourceFirst?: number
+  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) sourceLast?: number
+  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) cursorSeq?: number
+  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) firstSeqSeen?: number
+  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) headMissing?: number
+  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) behind?: number
+  @Column({ nullable: true }) @Field({ nullable: true }) reason?: string
+  @Column() @Field() checkedAt: Date
+  @CreateDateColumn() createdAt?: Date
+  @UpdateDateColumn() updatedAt?: Date
+}