@things-factory/headless-twin 10.0.19 → 10.1.0

package/dist-server/service/actuation/actuation-rule-resolver.d.ts

@@ -0,0 +1,19 @@
+import { ListParam } from '@things-factory/shell';
+export declare class TwinActuationRuleResolver {
+    twinActuationRules(params: ListParam, context: ResolverContext): Promise<any>;
+    /**
+     * 규칙을 세우거나 고친다.
+     *
+     * **낼 수 없는 종류는 저장하지 않는다.** 저장은 되는데 안 도는 규칙이 생기면 사람은 규칙이 걸린 줄로
+     * 읽는다. 판정과 같은 검사를 지난다(§`commandTypeGap`) — 두 벌이면 어긋난다.
+     */
+    saveTwinActuationRule(patch: any, context: ResolverContext): Promise<any>;
+    deleteTwinActuationRule(id: string, context: ResolverContext): Promise<any>;
+    /**
+     * **지금 한 번 돌린다** — 무엇을 냈고 무엇을 왜 안 냈는지 그대로 답한다.
+     *
+     * 낸 조치는 제안 상태로 남는다. 결재선에 올리는 것은 사람이 따로 한다(§`raiseTwinCommand`) — 규칙이
+     * 올리지 않는 이유가 여기에도 그대로 적용된다(결재선은 올린 사람 기준으로 풀린다).
+     */
+    runTwinActuationRules(instanceId: string, context: ResolverContext): Promise<any>;
+}

package/dist-server/service/actuation/actuation-rule-resolver.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinActuationRuleResolver = void 0;
+const tslib_1 = require("tslib");
+/*
+ * 규칙을 만들고 끄는 자리, 그리고 **지금 한 번 돌려 보는 자리**.
+ *
+ * ── 왜 「지금 돌린다」가 있나 ────────────────────────────────────────────
+ * 규칙을 만든 사람이 가장 먼저 묻는 것은 「이게 걸리나」다. 주기를 기다려 보라고 하면 그 사이에 무엇이
+ * 잘못됐는지 알 수 없고, 조건이 그때까지 살아 있을지도 모른다. 돌려 보면 **무엇을 냈고 무엇을 왜 안
+ * 냈는지**가 그 자리에서 답으로 온다.
+ */
+const type_graphql_1 = require("type-graphql");
+const ops_contract_1 = require("@operato/ops-contract");
+const shell_1 = require("@things-factory/shell");
+const twin_engine_js_1 = require("../../engine/twin-engine.js");
+const actuation_rule_js_1 = require("./actuation-rule.js");
+const rule_evaluate_js_1 = require("./rule-evaluate.js");
+const rule_runner_js_1 = require("./rule-runner.js");
+const command_store_js_1 = require("./command-store.js");
+const rule_wiring_js_1 = require("./rule-wiring.js");
+let TwinActuationRuleResolver = class TwinActuationRuleResolver {
+    async twinActuationRules(params, context) {
+        const domain = context.state.domain;
+        if (!domain?.id)
+            return { items: [], total: 0 };
+        const qb = (0, shell_1.getQueryBuilderFromListParams)({
+            repository: (0, shell_1.getRepository)(actuation_rule_js_1.TwinActuationRule),
+            params,
+            domain,
+            alias: 'r',
+            searchables: ['instanceId', 'name', 'attentionKind', 'commandType', 'lastSkipReason'],
+            sortables: ['createdAt', 'updatedAt', 'instanceId', 'attentionKind', 'commandType', 'lastRunAt'],
+            defaultLimit: 50,
+            maxLimit: 200
+        });
+        const [items, total] = await qb.getManyAndCount();
+        return { items, total };
+    }
+    /**
+     * 규칙을 세우거나 고친다.
+     *
+     * **낼 수 없는 종류는 저장하지 않는다.** 저장은 되는데 안 도는 규칙이 생기면 사람은 규칙이 걸린 줄로
+     * 읽는다. 판정과 같은 검사를 지난다(§`commandTypeGap`) — 두 벌이면 어긋난다.
+     */
+    async saveTwinActuationRule(patch, context) {
+        const { domain, user, tx } = context.state;
+        const instanceId = String(patch?.instanceId ?? '').trim();
+        if (!instanceId)
+            throw new Error('어느 트윈의 규칙인지 말해야 합니다 — 전역 규칙은 두지 않습니다');
+        const attentionKind = String(patch?.attentionKind ?? '').trim();
+        if (!attentionKind)
+            throw new Error('어느 관측에 걸 것인지 말해야 합니다');
+        const commandType = String(patch?.commandType ?? '').trim();
+        const gap = (0, rule_evaluate_js_1.commandTypeGap)(commandType, ops_contract_1.MES_COMMANDS, Object.values(ops_contract_1.CMD));
+        if (gap)
+            throw new Error(gap);
+        const repo = (0, shell_1.getRepository)(actuation_rule_js_1.TwinActuationRule, tx);
+        const saved = await repo.save({
+            ...(patch.id ? { id: patch.id } : {}),
+            domain,
+            instanceId,
+            name: patch.name ?? null,
+            attentionKind,
+            minSeverity: patch.minSeverity ?? null,
+            minHeldMs: patch.minHeldMs ?? null,
+            /* 비워 두면 기본값(한 시간)이 걸린다. 0 은 「기다리지 않는다」는 뜻이라 그대로 존중한다. */
+            cooldownMs: patch.cooldownMs ?? null,
+            commandType,
+            payloadTemplate: patch.payloadTemplate ?? null,
+            /* 비어 있음을 「끔」으로 읽지 않는다 — 새로 만든 규칙은 켜져 있는 것이 사람의 뜻이다. */
+            enabled: patch.enabled === false ? false : true,
+            ...(patch.id ? {} : { creator: user }),
+            updater: user
+        });
+        return saved;
+    }
+    async deleteTwinActuationRule(id, context) {
+        const { domain, tx } = context.state;
+        const result = await (0, shell_1.getRepository)(actuation_rule_js_1.TwinActuationRule, tx).delete({ id, domain: { id: domain.id } });
+        if (!result.affected)
+            throw new Error(`모르는 규칙입니다 (${id})`);
+        return { deleted: id };
+    }
+    /**
+     * **지금 한 번 돌린다** — 무엇을 냈고 무엇을 왜 안 냈는지 그대로 답한다.
+     *
+     * 낸 조치는 제안 상태로 남는다. 결재선에 올리는 것은 사람이 따로 한다(§`raiseTwinCommand`) — 규칙이
+     * 올리지 않는 이유가 여기에도 그대로 적용된다(결재선은 올린 사람 기준으로 풀린다).
+     */
+    async runTwinActuationRules(instanceId, context) {
+        const domainId = context.state.domain?.id;
+        if (!domainId)
+            throw new Error('테넌트를 알 수 없습니다');
+        /*
+         * 트랜잭션을 넘기지 않는다 — 이 자리는 여러 트윈을 돌고, 한 트윈이 실패해도 앞의 트윈이 낸 것은
+         * 남아야 한다. 한 덩어리로 묶으면 마지막 트윈의 실패가 앞의 결과를 전부 물린다.
+         */
+        const store = (0, command_store_js_1.databaseCommandStore)();
+        const owned = twin_engine_js_1.TwinEngine.ownedTwins(domainId).filter(t => !instanceId || t.instanceId === instanceId);
+        if (instanceId && !owned.length) {
+            throw new Error(`이 서버가 들고 있지 않은 트윈입니다 (${instanceId}) — 멈춰 있거나 다른 서버가 돌고 있습니다`);
+        }
+        const reports = await (0, rule_runner_js_1.runRulesOnce)({
+            ownedTwins: () => owned,
+            rulesOf: twin => (0, rule_wiring_js_1.rulesOf)(twin),
+            attentionsOf: rule_wiring_js_1.attentionsOf,
+            modeOf: rule_wiring_js_1.modeOf,
+            store,
+            specs: ops_contract_1.MES_COMMANDS,
+            nowMs: () => Date.now(),
+            noteRun: rule_wiring_js_1.noteRun
+        });
+        return { reports, proposed: reports.reduce((n, r) => n + r.proposed, 0) };
+    }
+};
+exports.TwinActuationRuleResolver = TwinActuationRuleResolver;
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
+        nullable: true,
+        description: 'List actuation rules with the standard list contract.'
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Args)(type => shell_1.ListParam)),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [shell_1.ListParam, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinActuationRuleResolver.prototype, "twinActuationRules", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@transaction'),
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
+    (0, type_graphql_1.Mutation)(returns => shell_1.ScalarObject, { description: 'Create or update one actuation rule.' }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('patch', type => shell_1.ScalarObject)),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [Object, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinActuationRuleResolver.prototype, "saveTwinActuationRule", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@transaction'),
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
+    (0, type_graphql_1.Mutation)(returns => shell_1.ScalarObject, { description: 'Delete one actuation rule.' }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('id')),
+    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)
+], TwinActuationRuleResolver.prototype, "deleteTwinActuationRule", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
+    (0, type_graphql_1.Mutation)(returns => shell_1.ScalarObject, { description: 'Evaluate actuation rules once now and report what happened.' }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId', { nullable: true })),
+    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)
+], TwinActuationRuleResolver.prototype, "runTwinActuationRules", null);
+exports.TwinActuationRuleResolver = TwinActuationRuleResolver = tslib_1.__decorate([
+    (0, type_graphql_1.Resolver)()
+], TwinActuationRuleResolver);
+//# sourceMappingURL=actuation-rule-resolver.js.map

package/dist-server/service/actuation/actuation-rule-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actuation-rule-resolver.js","sourceRoot":"","sources":["../../../server/service/actuation/actuation-rule-resolver.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 규칙을 만들고 끄는 자리, 그리고 **지금 한 번 돌려 보는 자리**.\n *\n * ── 왜 「지금 돌린다」가 있나 ────────────────────────────────────────────\n * 규칙을 만든 사람이 가장 먼저 묻는 것은 「이게 걸리나」다. 주기를 기다려 보라고 하면 그 사이에 무엇이\n * 잘못됐는지 알 수 없고, 조건이 그때까지 살아 있을지도 모른다. 돌려 보면 **무엇을 냈고 무엇을 왜 안\n * 냈는지**가 그 자리에서 답으로 온다.\n */\nimport { Arg, Args, Ctx, Directive, Mutation, Query, Resolver } from 'type-graphql'\n\nimport { CMD, MES_COMMANDS } from '@operato/ops-contract'\n\nimport { ListParam, ScalarObject, getQueryBuilderFromListParams, getRepository } from '@things-factory/shell'\n\nimport { TwinEngine } from '../../engine/twin-engine.js'\n\nimport { TwinActuationRule } from './actuation-rule.js'\nimport { commandTypeGap } from './rule-evaluate.js'\nimport { runRulesOnce } from './rule-runner.js'\nimport { databaseCommandStore } from './command-store.js'\nimport { rulesOf, noteRun, attentionsOf, modeOf } from './rule-wiring.js'\n\n@Resolver()\nexport class TwinActuationRuleResolver {\n  @Query(returns => ScalarObject, {\n    nullable: true,\n    description: 'List actuation rules with the standard list contract.'\n  })\n  async twinActuationRules(\n    @Args(type => ListParam) params: ListParam,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    const domain = context.state.domain\n    if (!domain?.id) return { items: [], total: 0 }\n\n    const qb = getQueryBuilderFromListParams({\n      repository: getRepository(TwinActuationRule),\n      params,\n      domain,\n      alias: 'r',\n      searchables: ['instanceId', 'name', 'attentionKind', 'commandType', 'lastSkipReason'],\n      sortables: ['createdAt', 'updatedAt', 'instanceId', 'attentionKind', 'commandType', 'lastRunAt'],\n      defaultLimit: 50,\n      maxLimit: 200\n    })\n\n    const [items, total] = await qb.getManyAndCount()\n    return { items, total }\n  }\n\n  /**\n   * 규칙을 세우거나 고친다.\n   *\n   * **낼 수 없는 종류는 저장하지 않는다.** 저장은 되는데 안 도는 규칙이 생기면 사람은 규칙이 걸린 줄로\n   * 읽는다. 판정과 같은 검사를 지난다(§`commandTypeGap`) — 두 벌이면 어긋난다.\n   */\n  @Directive('@transaction')\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => ScalarObject, { description: 'Create or update one actuation rule.' })\n  async saveTwinActuationRule(\n    @Arg('patch', type => ScalarObject) patch: any,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    const { domain, user, tx } = context.state\n\n    const instanceId = String(patch?.instanceId ?? '').trim()\n    if (!instanceId) throw new Error('어느 트윈의 규칙인지 말해야 합니다 — 전역 규칙은 두지 않습니다')\n\n    const attentionKind = String(patch?.attentionKind ?? '').trim()\n    if (!attentionKind) throw new Error('어느 관측에 걸 것인지 말해야 합니다')\n\n    const commandType = String(patch?.commandType ?? '').trim()\n    const gap = commandTypeGap(commandType, MES_COMMANDS, Object.values(CMD) as string[])\n    if (gap) throw new Error(gap)\n\n    const repo = getRepository(TwinActuationRule, tx)\n    const saved = await repo.save({\n      ...(patch.id ? { id: patch.id } : {}),\n      domain,\n      instanceId,\n      name: patch.name ?? null,\n      attentionKind,\n      minSeverity: patch.minSeverity ?? null,\n      minHeldMs: patch.minHeldMs ?? null,\n      /* 비워 두면 기본값(한 시간)이 걸린다. 0 은 「기다리지 않는다」는 뜻이라 그대로 존중한다. */\n      cooldownMs: patch.cooldownMs ?? null,\n      commandType,\n      payloadTemplate: patch.payloadTemplate ?? null,\n      /* 비어 있음을 「끔」으로 읽지 않는다 — 새로 만든 규칙은 켜져 있는 것이 사람의 뜻이다. */\n      enabled: patch.enabled === false ? false : true,\n      ...(patch.id ? {} : { creator: user }),\n      updater: user\n    } as any)\n\n    return saved\n  }\n\n  @Directive('@transaction')\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => ScalarObject, { description: 'Delete one actuation rule.' })\n  async deleteTwinActuationRule(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<any> {\n    const { domain, tx } = context.state\n    const result = await getRepository(TwinActuationRule, tx).delete({ id, domain: { id: domain.id } } as any)\n    if (!result.affected) throw new Error(`모르는 규칙입니다 (${id})`)\n    return { deleted: id }\n  }\n\n  /**\n   * **지금 한 번 돌린다** — 무엇을 냈고 무엇을 왜 안 냈는지 그대로 답한다.\n   *\n   * 낸 조치는 제안 상태로 남는다. 결재선에 올리는 것은 사람이 따로 한다(§`raiseTwinCommand`) — 규칙이\n   * 올리지 않는 이유가 여기에도 그대로 적용된다(결재선은 올린 사람 기준으로 풀린다).\n   */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => ScalarObject, { description: 'Evaluate actuation rules once now and report what happened.' })\n  async runTwinActuationRules(\n    @Arg('instanceId', { nullable: true }) instanceId: string,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    const domainId = context.state.domain?.id\n    if (!domainId) throw new Error('테넌트를 알 수 없습니다')\n\n    /*\n     * 트랜잭션을 넘기지 않는다 — 이 자리는 여러 트윈을 돌고, 한 트윈이 실패해도 앞의 트윈이 낸 것은\n     * 남아야 한다. 한 덩어리로 묶으면 마지막 트윈의 실패가 앞의 결과를 전부 물린다.\n     */\n    const store = databaseCommandStore()\n\n    const owned = TwinEngine.ownedTwins(domainId).filter(t => !instanceId || t.instanceId === instanceId)\n    if (instanceId && !owned.length) {\n      throw new Error(`이 서버가 들고 있지 않은 트윈입니다 (${instanceId}) — 멈춰 있거나 다른 서버가 돌고 있습니다`)\n    }\n\n    const reports = await runRulesOnce({\n      ownedTwins: () => owned,\n      rulesOf: twin => rulesOf(twin),\n      attentionsOf,\n      modeOf,\n      store,\n      specs: MES_COMMANDS,\n      nowMs: () => Date.now(),\n      noteRun\n    })\n\n    return { reports, proposed: reports.reduce((n, r) => n + r.proposed, 0) }\n  }\n}\n"]}

package/dist-server/service/actuation/actuation-rule.d.ts

@@ -0,0 +1,55 @@
+import { Domain } from '@things-factory/shell';
+import { User } from '@things-factory/auth-base';
+export declare class TwinActuationRule {
+    readonly id: string;
+    domain?: Domain;
+    domainId?: string;
+    /**
+     * **어느 트윈인가** — 전역 규칙을 두지 않는다.
+     *
+     * 라인이 공장마다 다르므로 한 규칙이 모든 트윈에 걸리면 어느 공장에서는 반드시 틀린다. 트윈을 지목하면
+     * 그 사실이 행에 드러나고, 화면이 「이 공장에 걸린 규칙」을 그대로 보여 줄 수 있다.
+     */
+    instanceId: string;
+    name?: string;
+    /** 어느 관측인가 — 커널의 안정 코드(`Attention.kind`). */
+    attentionKind: string;
+    minSeverity?: string;
+    /**
+     * **조건이 이만큼 이어졌을 때** 올린다.
+     *
+     * 없으면 처음 본 주기에 올린다. 깜빡이는 조건에 현장 지시가 나가는 것을 막는 유일한 칸이다.
+     */
+    minHeldMs?: number;
+    /**
+     * 무엇을 내는가 — **선언된 조치 종류**(`CommandTypeSpec.type`).
+     *
+     * 커널 자극(`CMD`)이 아니다. 자극을 적으면 판정이 「선언되지 않은 조치 종류」로 거절한다 — 그 값은
+     * 모델 상태를 바꾸는 것이고 현장에 나가는 지시가 아니다.
+     */
+    commandType: string;
+    /**
+     * 지시의 내용 — `{이름}` 을 관측의 값으로 바꿔 넣는다.
+     *
+     * 바꿀 값은 `Attention.params` 와 `anchor` 에서 온다. 바꿀 것이 없으면 그 칸을 비우고, 요구하는 칸이
+     * 비면 판정이 거절한다 — 지어낸 값으로 현장 지시를 만들지 않는다.
+     */
+    payloadTemplate?: any;
+    /**
+     * **한 번 낸 근거에 다시 내기까지 기다리는 시간(ms).**
+     *
+     * 비워 두면 기본값이 걸린다(한 시간). 0 으로 두면 기다리지 않는데, 그러면 승인하는 순간 같은 것이
+     * 다시 올라온다 — 걸어 보고 실제로 그 상태를 만들었다.
+     */
+    cooldownMs?: number;
+    /** 지우지 않고 끌 수 있어야 한다 — 잘못 낸 것을 본 사람이 가장 먼저 하려는 일이다. */
+    enabled?: boolean;
+    lastRunAt?: string;
+    proposedCount?: number;
+    /** 마지막에 왜 안 올렸나 — 사람 말로. */
+    lastSkipReason?: string;
+    creator?: User;
+    updater?: User;
+    createdAt?: Date;
+    updatedAt?: Date;
+}

package/dist-server/service/actuation/actuation-rule.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinActuationRule = void 0;
+const tslib_1 = require("tslib");
+/*
+ * **어느 관측에 어느 지시를 붙이는가** — 선언 한 행.
+ *
+ * ── 왜 표인가 (2026-09-01) ───────────────────────────────────────────────
+ * 규칙은 현장이 정한다. 「병목이 세 시간 넘으면 추가 생산을 올린다」는 그 공장의 정책이고, 코드에 박으면
+ * 공장마다 포크가 생긴다. 그리고 **끌 수 있어야 한다** — 규칙이 잘못 낸 것을 본 사람이 가장 먼저 하려는
+ * 일이 그것이다.
+ *
+ * ── 판정은 여기 없다 ─────────────────────────────────────────────────────
+ * 무엇을 올릴지는 `rule-evaluate.ts` 가 든다. 이 파일은 값을 담기만 한다 — 판정이 두 벌이 되면 화면과
+ * 서버가 다른 답을 낸다.
+ *
+ * ── 계약에 넣지 않았다 ───────────────────────────────────────────────────
+ * 이 규칙이 가리키는 두 값(`Attention.kind` · `CommandTypeSpec.type`)은 계약의 어휘다. 그러나 「그 둘을
+ * 어떻게 잇는가」는 이 호스트의 배선이다 — 커널은 규칙을 읽지 않고, 커널을 쓰는 다른 소비처가 이 표를
+ * 알 이유가 없다.
+ */
+const typeorm_1 = require("typeorm");
+const type_graphql_1 = require("type-graphql");
+const shell_1 = require("@things-factory/shell");
+const auth_base_1 = require("@things-factory/auth-base");
+let TwinActuationRule = class TwinActuationRule {
+};
+exports.TwinActuationRule = TwinActuationRule;
+tslib_1.__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    (0, type_graphql_1.Field)(type => type_graphql_1.ID, { description: 'Unique identifier of the rule.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinActuationRule.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: 'Tenant this rule belongs to.' }),
+    tslib_1.__metadata("design:type", shell_1.Domain)
+], TwinActuationRule.prototype, "domain", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((e) => e.domain),
+    tslib_1.__metadata("design:type", String)
+], TwinActuationRule.prototype, "domainId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Twin instance this rule applies to. There are no global rules.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinActuationRule.prototype, "instanceId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'What a person calls this rule.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinActuationRule.prototype, "name", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Observed condition kind in kernel vocabulary (Attention.kind).' }),
+    tslib_1.__metadata("design:type", String)
+], TwinActuationRule.prototype, "attentionKind", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Only at this severity or above: low, medium, high, critical.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinActuationRule.prototype, "minSeverity", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Propose only after the condition has held this long (ms).' }),
+    tslib_1.__metadata("design:type", Number)
+], TwinActuationRule.prototype, "minHeldMs", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Declared command type to propose. Not a kernel stimulus.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinActuationRule.prototype, "commandType", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'simple-json', nullable: true }),
+    (0, type_graphql_1.Field)(type => shell_1.ScalarObject, { nullable: true, description: 'Command payload template. {name} is filled from the observation.' }),
+    tslib_1.__metadata("design:type", Object)
+], TwinActuationRule.prototype, "payloadTemplate", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Wait this long before proposing again for the same cause (ms).' }),
+    tslib_1.__metadata("design:type", Number)
+], TwinActuationRule.prototype, "cooldownMs", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ default: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'A disabled rule is not evaluated. Turning off is not deleting.' }),
+    tslib_1.__metadata("design:type", Boolean)
+], TwinActuationRule.prototype, "enabled", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'When this rule was last evaluated (ISO 8601).' }),
+    tslib_1.__metadata("design:type", String)
+], TwinActuationRule.prototype, "lastRunAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'How many commands this rule has proposed in total.' }),
+    tslib_1.__metadata("design:type", Number)
+], TwinActuationRule.prototype, "proposedCount", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Why the last evaluation proposed nothing, when it did not.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinActuationRule.prototype, "lastSkipReason", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => auth_base_1.User, { nullable: true }),
+    (0, type_graphql_1.Field)(type => auth_base_1.User, { nullable: true }),
+    tslib_1.__metadata("design:type", auth_base_1.User)
+], TwinActuationRule.prototype, "creator", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => auth_base_1.User, { nullable: true }),
+    (0, type_graphql_1.Field)(type => auth_base_1.User, { nullable: true }),
+    tslib_1.__metadata("design:type", auth_base_1.User)
+], TwinActuationRule.prototype, "updater", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.CreateDateColumn)(),
+    (0, type_graphql_1.Field)({ nullable: true }),
+    tslib_1.__metadata("design:type", Date)
+], TwinActuationRule.prototype, "createdAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.UpdateDateColumn)(),
+    (0, type_graphql_1.Field)({ nullable: true }),
+    tslib_1.__metadata("design:type", Date)
+], TwinActuationRule.prototype, "updatedAt", void 0);
+exports.TwinActuationRule = TwinActuationRule = tslib_1.__decorate([
+    (0, typeorm_1.Entity)()
+    /* 판정이 이 두 칸으로 묻는다 — 이 테넌트의 · 이 트윈의 규칙. */
+    ,
+    (0, typeorm_1.Index)('ix_twin_actuation_rule_0', (e) => [e.domain, e.instanceId]),
+    (0, type_graphql_1.ObjectType)({ description: 'One rule mapping an observed condition to a field instruction that needs approval.' })
+], TwinActuationRule);
+//# sourceMappingURL=actuation-rule.js.map

package/dist-server/service/actuation/actuation-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actuation-rule.js","sourceRoot":"","sources":["../../../server/service/actuation/actuation-rule.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * **어느 관측에 어느 지시를 붙이는가** — 선언 한 행.\n *\n * ── 왜 표인가 (2026-09-01) ───────────────────────────────────────────────\n * 규칙은 현장이 정한다. 「병목이 세 시간 넘으면 추가 생산을 올린다」는 그 공장의 정책이고, 코드에 박으면\n * 공장마다 포크가 생긴다. 그리고 **끌 수 있어야 한다** — 규칙이 잘못 낸 것을 본 사람이 가장 먼저 하려는\n * 일이 그것이다.\n *\n * ── 판정은 여기 없다 ─────────────────────────────────────────────────────\n * 무엇을 올릴지는 `rule-evaluate.ts` 가 든다. 이 파일은 값을 담기만 한다 — 판정이 두 벌이 되면 화면과\n * 서버가 다른 답을 낸다.\n *\n * ── 계약에 넣지 않았다 ───────────────────────────────────────────────────\n * 이 규칙이 가리키는 두 값(`Attention.kind` · `CommandTypeSpec.type`)은 계약의 어휘다. 그러나 「그 둘을\n * 어떻게 잇는가」는 이 호스트의 배선이다 — 커널은 규칙을 읽지 않고, 커널을 쓰는 다른 소비처가 이 표를\n * 알 이유가 없다.\n */\nimport { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId, UpdateDateColumn } from 'typeorm'\nimport { Field, ID, ObjectType } from 'type-graphql'\n\nimport { Domain, ScalarObject } from '@things-factory/shell'\nimport { User } from '@things-factory/auth-base'\n\n@Entity()\n/* 판정이 이 두 칸으로 묻는다 — 이 테넌트의 · 이 트윈의 규칙. */\n@Index('ix_twin_actuation_rule_0', (e: TwinActuationRule) => [e.domain, e.instanceId])\n@ObjectType({ description: 'One rule mapping an observed condition to a field instruction that needs approval.' })\nexport class TwinActuationRule {\n  @PrimaryGeneratedColumn('uuid')\n  @Field(type => ID, { description: 'Unique identifier of the rule.' })\n  readonly id: string\n\n  @ManyToOne(type => Domain)\n  @Field(type => Domain, { nullable: true, description: 'Tenant this rule belongs to.' })\n  domain?: Domain\n\n  @RelationId((e: TwinActuationRule) => e.domain)\n  domainId?: string\n\n  /**\n   * **어느 트윈인가** — 전역 규칙을 두지 않는다.\n   *\n   * 라인이 공장마다 다르므로 한 규칙이 모든 트윈에 걸리면 어느 공장에서는 반드시 틀린다. 트윈을 지목하면\n   * 그 사실이 행에 드러나고, 화면이 「이 공장에 걸린 규칙」을 그대로 보여 줄 수 있다.\n   */\n  @Column()\n  @Field({ description: 'Twin instance this rule applies to. There are no global rules.' })\n  instanceId: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'What a person calls this rule.' })\n  name?: string\n\n  /** 어느 관측인가 — 커널의 안정 코드(`Attention.kind`). */\n  @Column()\n  @Field({ description: 'Observed condition kind in kernel vocabulary (Attention.kind).' })\n  attentionKind: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Only at this severity or above: low, medium, high, critical.' })\n  minSeverity?: string\n\n  /**\n   * **조건이 이만큼 이어졌을 때** 올린다.\n   *\n   * 없으면 처음 본 주기에 올린다. 깜빡이는 조건에 현장 지시가 나가는 것을 막는 유일한 칸이다.\n   */\n  @Column({ type: 'int', nullable: true })\n  @Field({ nullable: true, description: 'Propose only after the condition has held this long (ms).' })\n  minHeldMs?: number\n\n  /**\n   * 무엇을 내는가 — **선언된 조치 종류**(`CommandTypeSpec.type`).\n   *\n   * 커널 자극(`CMD`)이 아니다. 자극을 적으면 판정이 「선언되지 않은 조치 종류」로 거절한다 — 그 값은\n   * 모델 상태를 바꾸는 것이고 현장에 나가는 지시가 아니다.\n   */\n  @Column()\n  @Field({ description: 'Declared command type to propose. Not a kernel stimulus.' })\n  commandType: string\n\n  /**\n   * 지시의 내용 — `{이름}` 을 관측의 값으로 바꿔 넣는다.\n   *\n   * 바꿀 값은 `Attention.params` 와 `anchor` 에서 온다. 바꿀 것이 없으면 그 칸을 비우고, 요구하는 칸이\n   * 비면 판정이 거절한다 — 지어낸 값으로 현장 지시를 만들지 않는다.\n   */\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => ScalarObject, { nullable: true, description: 'Command payload template. {name} is filled from the observation.' })\n  payloadTemplate?: any\n\n  /**\n   * **한 번 낸 근거에 다시 내기까지 기다리는 시간(ms).**\n   *\n   * 비워 두면 기본값이 걸린다(한 시간). 0 으로 두면 기다리지 않는데, 그러면 승인하는 순간 같은 것이\n   * 다시 올라온다 — 걸어 보고 실제로 그 상태를 만들었다.\n   */\n  @Column({ type: 'int', nullable: true })\n  @Field({ nullable: true, description: 'Wait this long before proposing again for the same cause (ms).' })\n  cooldownMs?: number\n\n  /** 지우지 않고 끌 수 있어야 한다 — 잘못 낸 것을 본 사람이 가장 먼저 하려는 일이다. */\n  @Column({ default: true })\n  @Field({ nullable: true, description: 'A disabled rule is not evaluated. Turning off is not deleting.' })\n  enabled?: boolean\n\n  /* ── 마지막 판정의 기록 ─────────────────────────────────────────────────\n   * 규칙이 **아무것도 올리지 않을 때** 사람이 알 수 있어야 한다. 조용히 안 도는 규칙과 조건이 없어서 안\n   * 올리는 규칙은 화면에서 똑같이 보이고, 그 둘을 구별하지 못하면 사람은 규칙이 도는 줄 안다.\n   */\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'When this rule was last evaluated (ISO 8601).' })\n  lastRunAt?: string\n\n  @Column({ type: 'int', nullable: true })\n  @Field({ nullable: true, description: 'How many commands this rule has proposed in total.' })\n  proposedCount?: number\n\n  /** 마지막에 왜 안 올렸나 — 사람 말로. */\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Why the last evaluation proposed nothing, when it did not.' })\n  lastSkipReason?: string\n\n  @ManyToOne(type => User, { nullable: true })\n  @Field(type => User, { nullable: true })\n  creator?: User\n\n  @ManyToOne(type => User, { nullable: true })\n  @Field(type => User, { nullable: true })\n  updater?: User\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/actuation/approval-gateway.d.ts

@@ -0,0 +1,20 @@
+import type { StoredCommand } from './command-dispatcher.js';
+/** 결재선에 올리는 자리 — 앱이 구현한다. */
+export interface ApprovalGateway {
+    /** 화면과 오류 문장에 쓰는 이름. 「어디서 승인하는가」를 사람에게 말해야 한다. */
+    label: string;
+    /**
+     * 이 커맨드를 결재선에 올린다.
+     *
+     * 돌려주는 것은 **올라간 자리의 식별자**다. 이 값이 커맨드 행에 적히고, 그 뒤로는 직접 결정이 막힌다
+     * — 문이 두 벌이면 한쪽 기록에만 남는 승인이 생긴다.
+     *
+     * `context` 는 리졸버 문맥 그대로 넘긴다(트랜잭션·로그인한 사람·테넌트). 이 패키지가 그 모양을 알면
+     * 앱의 인증 구조를 여기서 다시 정의하게 된다.
+     */
+    request(command: StoredCommand, context: any): Promise<string>;
+}
+/** 앱이 부팅에서 한 번 부른다. */
+export declare function setApprovalGateway(next: ApprovalGateway): void;
+/** 등록된 것이 없으면 `undefined` — 없음을 없음으로 답한다. */
+export declare function approvalGateway(): ApprovalGateway | undefined;

package/dist-server/service/actuation/approval-gateway.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setApprovalGateway = setApprovalGateway;
+exports.approvalGateway = approvalGateway;
+let gateway;
+/** 앱이 부팅에서 한 번 부른다. */
+function setApprovalGateway(next) {
+    gateway = next;
+}
+/** 등록된 것이 없으면 `undefined` — 없음을 없음으로 답한다. */
+function approvalGateway() {
+    return gateway;
+}
+//# sourceMappingURL=approval-gateway.js.map

package/dist-server/service/actuation/approval-gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-gateway.js","sourceRoot":"","sources":["../../../server/service/actuation/approval-gateway.ts"],"names":[],"mappings":";;AAoCA,gDAEC;AAGD,0CAEC;AAVD,IAAI,OAAoC,CAAA;AAExC,uBAAuB;AACvB,SAAgB,kBAAkB,CAAC,IAAqB;IACtD,OAAO,GAAG,IAAI,CAAA;AAChB,CAAC;AAED,6CAA6C;AAC7C,SAAgB,eAAe;IAC7B,OAAO,OAAO,CAAA;AAChB,CAAC","sourcesContent":["/*\n * **승인을 누가 받는가** — 그 자리를 밖으로 낸다.\n *\n * ── 왜 시임인가 (2026-08-31) ─────────────────────────────────────────────\n * 승인은 이미 이 저장소에 있다. `@things-factory/worklist` 가 결재선·위임·상신·「내가 승인할 것」 목록과\n * 승인 화면까지 들고 있다. 그것을 다시 만들면 두 벌이 되고, 사고 뒤에 「어느 쪽 기록이 진짜인가」를\n * 묻게 된다.\n *\n * 그런데 headless-twin 은 worklist 를 부를 수 없다 — worklist 는 조직도(Employee·Department·Role)와\n * 화면 27쪽을 데리고 오는 업무 모듈이고, 이 패키지는 커널을 안는 헤드리스 서버다. 의존을 그 방향으로\n * 걸면 커널을 쓰는 모든 배포가 조직도를 지게 된다.\n *\n * 그래서 **이 패키지는 자리만 만들고, 앱이 채운다**(operato-twin). 채우지 않은 배포에서는 게이트가\n * 사라지지 않는다 — 승인 없이 지나가는 것이 아니라, 아래 §`twinCommands` 의 직접 결정이 유일한 문이 된다.\n */\nimport type { StoredCommand } from './command-dispatcher.js'\n\n/** 결재선에 올리는 자리 — 앱이 구현한다. */\nexport interface ApprovalGateway {\n  /** 화면과 오류 문장에 쓰는 이름. 「어디서 승인하는가」를 사람에게 말해야 한다. */\n  label: string\n  /**\n   * 이 커맨드를 결재선에 올린다.\n   *\n   * 돌려주는 것은 **올라간 자리의 식별자**다. 이 값이 커맨드 행에 적히고, 그 뒤로는 직접 결정이 막힌다\n   * — 문이 두 벌이면 한쪽 기록에만 남는 승인이 생긴다.\n   *\n   * `context` 는 리졸버 문맥 그대로 넘긴다(트랜잭션·로그인한 사람·테넌트). 이 패키지가 그 모양을 알면\n   * 앱의 인증 구조를 여기서 다시 정의하게 된다.\n   */\n  request(command: StoredCommand, context: any): Promise<string>\n}\n\nlet gateway: ApprovalGateway | undefined\n\n/** 앱이 부팅에서 한 번 부른다. */\nexport function setApprovalGateway(next: ApprovalGateway): void {\n  gateway = next\n}\n\n/** 등록된 것이 없으면 `undefined` — 없음을 없음으로 답한다. */\nexport function approvalGateway(): ApprovalGateway | undefined {\n  return gateway\n}\n"]}

package/dist-server/service/actuation/catch-up-effects.d.ts

@@ -0,0 +1,16 @@
+import type { CommandStore } from './command-dispatcher.js';
+export interface CatchUpResult {
+    /** 효과를 기다리던 조치 수. */
+    awaiting: number;
+    /** 이번에 효과를 적은 조치 수. */
+    recorded: number;
+    /** 저널에 보고가 아직 없던 조치 수 — 저쪽이 아직 아무 말도 안 한 것이다. */
+    silent: number;
+}
+/**
+ * 이 도메인에서 놓친 보고를 한 번 backfill 한다.
+ *
+ * **던지지 않는다.** 주기에서 부르고, 여기서 터지면 그 주기가 멈춘다. 그리고 이 일은 다음 바퀴에
+ * 다시 해도 같은 결과가 나온다 — 급할 것이 없다.
+ */
+export declare function catchUpEffects(domainId: string, store: CommandStore): Promise<CatchUpResult>;

package/dist-server/service/actuation/catch-up-effects.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.catchUpEffects = catchUpEffects;
+/*
+ * **놓친 보고를 backfill 한다** — 유입 자리에서 잇는 길(§`settle-effects.ts`)의 짝.
+ *
+ * ── 왜 필요한가 (2026-09-02, 실제로 하나 놓쳤다) ──────────────────────────────
+ * 유입 자리에서만 이으면, **우리가 못 듣고 있던 동안 온 보고는 영원히 사라진다.**
+ *
+ *   10:13  MES 가 WO-20260902-005 를 현장에 냄. order.status 가 트윈에 도착
+ *   19:21  잇는 배선을 산출물에 넣음
+ *   → 그 보고는 저널에 남았는데 조치에는 안 이어졌다. 다시 오지 않는다
+ *
+ * 같은 일이 트윈이 내려가 있는 사이, 커넥터를 고치는 사이, 프로세스가 죽었다 서는 사이에 난다.
+ * 관측은 되풀이해 주지 않는다.
+ *
+ * ── 왜 저널을 읽나 ───────────────────────────────────────────────────────────
+ * 저널에 `orderId` 가 **컬럼으로** 있고 인덱스도 있다(`ix_twin_event_4 (domain, instanceId, orderId)`
+ * — 「이 오더가 어디까지 갔나」). 그래서 「우리가 낸 지시들의 마지막 보고」를 값싸게 물을 수 있다.
+ * JSON 안을 뒤지지 않으므로 드라이버 다섯에서 같이 돈다.
+ *
+ * ── 왜 방향이 반대인가 ───────────────────────────────────────────────────────
+ * 유입 쪽은 **보고에서 조치를 찾는다**(보고가 많고 조치가 적다 — 그래서 식별자를 모아 한 번 묻는다).
+ * 이쪽은 **조치에서 보고를 찾는다.** 효과를 기다리는 조치는 몇 건이고, 그 몇 건의 식별자로 저널을
+ * 물으면 끝난다. 저널 전체를 주사하지 않는다.
+ */
+const ops_contract_1 = require("@operato/ops-contract");
+const shell_1 = require("@things-factory/shell");
+const log_js_1 = require("../../engine/log.js");
+const twin_event_js_1 = require("../twin-event/twin-event.js");
+const effect_match_js_1 = require("./effect-match.js");
+/**
+ * 이 도메인에서 놓친 보고를 한 번 backfill 한다.
+ *
+ * **던지지 않는다.** 주기에서 부르고, 여기서 터지면 그 주기가 멈춘다. 그리고 이 일은 다음 바퀴에
+ * 다시 해도 같은 결과가 나온다 — 급할 것이 없다.
+ */
+async function catchUpEffects(domainId, store) {
+    const none = { awaiting: 0, recorded: 0, silent: 0 };
+    if (!store.awaitingEffect || !store.recordEffects) {
+        (0, log_js_1.twinWarn)('[actuation] 놓친 보고를 backfill 할 수 없다 — 저장소에 awaitingEffect 나 recordEffects 가 없다. ' +
+            '못 듣고 있던 동안 온 보고는 영원히 이어지지 않는다.');
+        return none;
+    }
+    try {
+        const commands = await store.awaitingEffect(domainId);
+        if (!commands.length)
+            return none;
+        /* 트윈마다 묶는다 — 저널 질의가 트윈 단위로 인덱스를 탄다. */
+        const byTwin = new Map();
+        for (const c of commands) {
+            if (!c.dispatchRef)
+                continue;
+            const list = byTwin.get(c.instanceId) ?? [];
+            list.push(c);
+            byTwin.set(c.instanceId, list);
+        }
+        let recorded = 0;
+        let silent = 0;
+        for (const [instanceId, list] of byTwin) {
+            const observations = await latestOrderReports(domainId, instanceId, list.map(c => c.dispatchRef));
+            const seen = new Set(observations.map(o => o.orderId));
+            silent += list.filter(c => !seen.has(c.dispatchRef)).length;
+            const { updates } = (0, effect_match_js_1.matchEffects)({
+                observations,
+                byRef: new Map(list.map(c => [c.dispatchRef, { id: c.id, dispatchRef: c.dispatchRef, ...(c.effect ? { effect: c.effect } : {}) }]))
+            });
+            /*
+             * **이미 적힌 것과 같으면 적지 않는다.** 주기마다 부르므로, 안 걸러 내면 같은 보고로 `seen` 이
+             * 영원히 는다 — 「몇 번 보고됐나」가 「몇 번 backfill 했나」가 된다.
+             */
+            const changed = updates.filter(u => {
+                const before = list.find(c => c.id === u.commandId)?.effect;
+                return !before || before.status !== u.status || before.at !== u.at;
+            });
+            if (changed.length) {
+                await store.recordEffects(domainId, changed);
+                recorded += changed.length;
+            }
+        }
+        return { awaiting: commands.length, recorded, silent };
+    }
+    catch (e) {
+        (0, log_js_1.twinWarn)(`[actuation] 놓친 보고를 backfill하다 실패했다 — ${String(e?.message ?? e).slice(0, 200)}`);
+        return none;
+    }
+}
+/**
+ * 이 트윈에서 그 오더들의 **마지막** 상태 보고를 읽는다.
+ *
+ * ── 왜 오더마다 따로 묻나 ──────────────────────────────────────────────────
+ * 한 번에 묶어 물으면 그 오더들의 보고를 **전부** 받게 된다. 오더 하나가 수백 번 보고될 수 있고
+ * (초안 → 나감 → 진행 → 완료, 그리고 수량이 바뀔 때마다), 그러면 상한 없이 저널을 읽는 자리가 된다.
+ *
+ * 그래서 오더마다 `take: 1` 로 최신 하나만 읽는다. 질의 수가 조치 수만큼 늘지만, **효과를 기다리는
+ * 조치는 몇 건**이다(넘긴 것만, 그것도 식별자가 있는 것만). 몇 건에 몇 질의는 값이 아니고, 상한 없이
+ * 원장을 읽는 것은 값이다.
+ *
+ * `revision` 내림차순이 「나중」의 정본이다 — 시각이 같은 보고가 여럿 올 수 있고(같은 밀리초에 둘이
+ * 실제로 있었다), 그때 무엇이 나중인지는 원장의 순서가 답한다.
+ */
+async function latestOrderReports(domainId, instanceId, refs) {
+    const out = [];
+    const repo = (0, shell_1.getRepository)(twin_event_js_1.TwinEvent);
+    for (const orderId of new Set(refs)) {
+        const rows = await repo.find({
+            where: { domain: { id: domainId }, instanceId, eventType: ops_contract_1.OP_EVENT.order, orderId },
+            order: { revision: 'DESC' },
+            take: 1
+        });
+        const row = rows[0];
+        const data = row?.payload?.data;
+        if (!data)
+            continue;
+        /* 봉투에 적힌 시각을 쓴다 — 저장 시각이 아니다. 없으면 판정이 거른다. */
+        out.push({ orderId, status: String(data.status ?? ''), at: row.payload?.eventTime });
+    }
+    return out;
+}
+//# sourceMappingURL=catch-up-effects.js.map

package/dist-server/service/actuation/catch-up-effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catch-up-effects.js","sourceRoot":"","sources":["../../../server/service/actuation/catch-up-effects.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * **놓친 보고를 backfill 한다** — 유입 자리에서 잇는 길(§`settle-effects.ts`)의 짝.\n *\n * ── 왜 필요한가 (2026-09-02, 실제로 하나 놓쳤다) ──────────────────────────────\n * 유입 자리에서만 이으면, **우리가 못 듣고 있던 동안 온 보고는 영원히 사라진다.**\n *\n *   10:13  MES 가 WO-20260902-005 를 현장에 냄. order.status 가 트윈에 도착\n *   19:21  잇는 배선을 산출물에 넣음\n *   → 그 보고는 저널에 남았는데 조치에는 안 이어졌다. 다시 오지 않는다\n *\n * 같은 일이 트윈이 내려가 있는 사이, 커넥터를 고치는 사이, 프로세스가 죽었다 서는 사이에 난다.\n * 관측은 되풀이해 주지 않는다.\n *\n * ── 왜 저널을 읽나 ───────────────────────────────────────────────────────────\n * 저널에 `orderId` 가 **컬럼으로** 있고 인덱스도 있다(`ix_twin_event_4 (domain, instanceId, orderId)`\n * — 「이 오더가 어디까지 갔나」). 그래서 「우리가 낸 지시들의 마지막 보고」를 값싸게 물을 수 있다.\n * JSON 안을 뒤지지 않으므로 드라이버 다섯에서 같이 돈다.\n *\n * ── 왜 방향이 반대인가 ───────────────────────────────────────────────────────\n * 유입 쪽은 **보고에서 조치를 찾는다**(보고가 많고 조치가 적다 — 그래서 식별자를 모아 한 번 묻는다).\n * 이쪽은 **조치에서 보고를 찾는다.** 효과를 기다리는 조치는 몇 건이고, 그 몇 건의 식별자로 저널을\n * 물으면 끝난다. 저널 전체를 주사하지 않는다.\n */\nimport { OP_EVENT } from '@operato/ops-contract'\n\nimport { getRepository } from '@things-factory/shell'\n\nimport { twinWarn } from '../../engine/log.js'\nimport { TwinEvent } from '../twin-event/twin-event.js'\n\nimport type { CommandStore, StoredCommand } from './command-dispatcher.js'\nimport { matchEffects, type OrderObservation } from './effect-match.js'\n\nexport interface CatchUpResult {\n  /** 효과를 기다리던 조치 수. */\n  awaiting: number\n  /** 이번에 효과를 적은 조치 수. */\n  recorded: number\n  /** 저널에 보고가 아직 없던 조치 수 — 저쪽이 아직 아무 말도 안 한 것이다. */\n  silent: number\n}\n\n/**\n * 이 도메인에서 놓친 보고를 한 번 backfill 한다.\n *\n * **던지지 않는다.** 주기에서 부르고, 여기서 터지면 그 주기가 멈춘다. 그리고 이 일은 다음 바퀴에\n * 다시 해도 같은 결과가 나온다 — 급할 것이 없다.\n */\nexport async function catchUpEffects(domainId: string, store: CommandStore): Promise<CatchUpResult> {\n  const none: CatchUpResult = { awaiting: 0, recorded: 0, silent: 0 }\n\n  if (!store.awaitingEffect || !store.recordEffects) {\n    twinWarn(\n      '[actuation] 놓친 보고를 backfill 할 수 없다 — 저장소에 awaitingEffect 나 recordEffects 가 없다. ' +\n        '못 듣고 있던 동안 온 보고는 영원히 이어지지 않는다.'\n    )\n    return none\n  }\n\n  try {\n    const commands = await store.awaitingEffect(domainId)\n    if (!commands.length) return none\n\n    /* 트윈마다 묶는다 — 저널 질의가 트윈 단위로 인덱스를 탄다. */\n    const byTwin = new Map<string, StoredCommand[]>()\n    for (const c of commands) {\n      if (!c.dispatchRef) continue\n      const list = byTwin.get(c.instanceId) ?? []\n      list.push(c)\n      byTwin.set(c.instanceId, list)\n    }\n\n    let recorded = 0\n    let silent = 0\n\n    for (const [instanceId, list] of byTwin) {\n      const observations = await latestOrderReports(\n        domainId,\n        instanceId,\n        list.map(c => c.dispatchRef!)\n      )\n\n      const seen = new Set(observations.map(o => o.orderId))\n      silent += list.filter(c => !seen.has(c.dispatchRef!)).length\n\n      const { updates } = matchEffects({\n        observations,\n        byRef: new Map(\n          list.map(c => [c.dispatchRef!, { id: c.id, dispatchRef: c.dispatchRef!, ...(c.effect ? { effect: c.effect } : {}) }])\n        )\n      })\n\n      /*\n       * **이미 적힌 것과 같으면 적지 않는다.** 주기마다 부르므로, 안 걸러 내면 같은 보고로 `seen` 이\n       * 영원히 는다 — 「몇 번 보고됐나」가 「몇 번 backfill 했나」가 된다.\n       */\n      const changed = updates.filter(u => {\n        const before = list.find(c => c.id === u.commandId)?.effect\n        return !before || before.status !== u.status || before.at !== u.at\n      })\n\n      if (changed.length) {\n        await store.recordEffects(domainId, changed)\n        recorded += changed.length\n      }\n    }\n\n    return { awaiting: commands.length, recorded, silent }\n  } catch (e: any) {\n    twinWarn(`[actuation] 놓친 보고를 backfill하다 실패했다 — ${String(e?.message ?? e).slice(0, 200)}`)\n    return none\n  }\n}\n\n/**\n * 이 트윈에서 그 오더들의 **마지막** 상태 보고를 읽는다.\n *\n * ── 왜 오더마다 따로 묻나 ──────────────────────────────────────────────────\n * 한 번에 묶어 물으면 그 오더들의 보고를 **전부** 받게 된다. 오더 하나가 수백 번 보고될 수 있고\n * (초안 → 나감 → 진행 → 완료, 그리고 수량이 바뀔 때마다), 그러면 상한 없이 저널을 읽는 자리가 된다.\n *\n * 그래서 오더마다 `take: 1` 로 최신 하나만 읽는다. 질의 수가 조치 수만큼 늘지만, **효과를 기다리는\n * 조치는 몇 건**이다(넘긴 것만, 그것도 식별자가 있는 것만). 몇 건에 몇 질의는 값이 아니고, 상한 없이\n * 원장을 읽는 것은 값이다.\n *\n * `revision` 내림차순이 「나중」의 정본이다 — 시각이 같은 보고가 여럿 올 수 있고(같은 밀리초에 둘이\n * 실제로 있었다), 그때 무엇이 나중인지는 원장의 순서가 답한다.\n */\nasync function latestOrderReports(\n  domainId: string,\n  instanceId: string,\n  refs: readonly string[]\n): Promise<OrderObservation[]> {\n  const out: OrderObservation[] = []\n  const repo = getRepository(TwinEvent)\n\n  for (const orderId of new Set(refs)) {\n    const rows = await repo.find({\n      where: { domain: { id: domainId }, instanceId, eventType: OP_EVENT.order, orderId },\n      order: { revision: 'DESC' },\n      take: 1\n    } as any)\n\n    const row: any = rows[0]\n    const data = row?.payload?.data\n    if (!data) continue\n\n    /* 봉투에 적힌 시각을 쓴다 — 저장 시각이 아니다. 없으면 판정이 거른다. */\n    out.push({ orderId, status: String(data.status ?? ''), at: row.payload?.eventTime })\n  }\n  return out\n}\n"]}