@things-factory/headless-twin 10.0.18 → 10.1.0

package/dist-server/service/actuation/settle-effects.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orderObservationsIn = orderObservationsIn;
+exports.settleEffects = settleEffects;
+/*
+ * **관측이 들어올 때 나간 지시와 잇는다** — 폐루프의 배선. 판단은 `effect-match.ts` 가 한다.
+ *
+ * ── 무엇이 실측으로 확인됐나 (2026-09-02) ─────────────────────────────────────
+ * 인티그레이션 레인이 조치 둘을 MES 까지 걸었다. 트윈 쪽 두 행이 **구별되지 않았다.**
+ *
+ *   325e9bb1  acked  WO-20260902-004  지시서 붙음      MES 에서 DRAFT
+ *   57428362  acked  WO-20260902-005  지시서 못 붙음   MES 에서 DRAFT
+ *
+ * `state`·`dispatch_ref`·`error` 가 셋 다 같다. 그래서 화면은 둘 다 「나갔다」로 읽는데, 둘 다 아직
+ * 현장에 안 갔다. `acked` 의 뜻은 **「저쪽이 받았다」**까지다.
+ *
+ * 빠져나오는 것은 관측이다 — 저쪽이 그 오더를 현장에 내면 `order.status` 가 우리가 받은 식별자로
+ * 돌아온다. 그것을 이 파일이 잇는다.
+ *
+ * ── 왜 유입 자리인가 ─────────────────────────────────────────────────────────
+ * 관측의 **시각**이 봉투에만 있다. 나중에 커널 상태에서 읽으면 「지금」밖에 알 수 없고, 그것은 보고된
+ * 시각이 아니라 우리가 처리한 시각이다. 없는 사실을 만들지 않는다.
+ *
+ * ── 어디서 부르나 ───────────────────────────────────────────────────────────
+ *
+ *   routes.ts            훅으로 밀려 들어온 것
+ *   reference-live.ts    커넥터가 이어 내는 것 · 폴링으로 물어 온 것
+ *
+ * **백필(`backfill-period-facts.ts`)에서는 부르지 않는다.** 그것은 마감된 구간의 저널을 채우는
+ * 일이고, 이 자리가 답하는 것은 「방금 보낸 지시가 어떻게 됐나」다. 저널을 고치는 작업이 조치 기록을
+ * 바꾸게 두면, 백필을 다시 돌릴 때마다 같은 보고가 다시 세어진다(`seen` 이 는다).
+ *
+ * 그래서 지난 기록에서 효과가 확인되는 경우는 지금 다루지 않는다. 필요해지면 그때는 **백필 전용
+ * 경로**로 만들 일이다 — 몇 번 세었나가 아니라 「그때 이랬다」만 적는 자리다.
+ *
+ * ── 값은 얼마나 드나 ─────────────────────────────────────────────────────────
+ * 오더 보고가 든 묶음마다 질의 하나다. 조치가 하나도 안 나간 도메인에서도 그 질의가 돈다 — 지금
+ * 규모에서 그 값은 작지만 공짜라고 말하지 않는다. 더 줄이려면 「효과를 기다리는 식별자」를 프로세스가
+ * 들고 있어야 하고, 그러면 재기동 때 저장소에서 되세우는 자리가 하나 더 생긴다. 그것이 필요해지는
+ * 시점은 **오더 보고가 초당 수백 건 오는 도메인**이다.
+ */
+const ops_contract_1 = require("@operato/ops-contract");
+const log_js_1 = require("../../engine/log.js");
+const effect_match_js_1 = require("./effect-match.js");
+/** 봉투에서 오더 보고만 골라낸다 — 다른 어휘는 보지 않는다. */
+function orderObservationsIn(envelopes) {
+    const out = [];
+    for (const e of envelopes ?? []) {
+        if (e?.eventType !== ops_contract_1.OP_EVENT.order)
+            continue;
+        const data = e?.data;
+        if (!data?.orderId)
+            continue;
+        /*
+         * 시각은 **봉투의 것**을 쓴다. 보고한 쪽이 말한 시각이고, 우리가 처리한 시각이 아니다.
+         * 없으면 `matchEffects` 가 거른다 — 여기서 「지금」으로 채우지 않는다.
+         */
+        out.push({ orderId: String(data.orderId), status: String(data.status ?? ''), at: e?.eventTime });
+    }
+    return out;
+}
+/**
+ * 이 묶음의 오더 보고를 나간 지시와 잇는다 — **아무것도 못 이어도 조용히 지난다.**
+ *
+ * 유입 경로에서 부른다. 그래서 **던지지 않는다** — 효과를 적다 실패해서 관측 유입이 멈추면, 고치는
+ * 동안 트윈이 눈을 감는다. 효과는 다음 보고에 다시 이을 수 있고 관측은 다시 오지 않는다.
+ */
+async function settleEffects(args) {
+    const { domainId, envelopes, store } = args;
+    const none = { recorded: 0, unmatched: 0 };
+    const observations = orderObservationsIn(envelopes);
+    if (!observations.length)
+        return none;
+    /*
+     * 저장소가 두 자리를 안 갖추면 이을 길이 없다. **조용히 지나지 않고 말한다** — 이 상태에서는
+     * 넘긴 지시가 저쪽에서 어떻게 됐는지 영원히 모르고, 화면은 그 사실을 알 수 없다.
+     */
+    if (!store.byDispatchRef || !store.recordEffects) {
+        (0, log_js_1.twinWarn)('[actuation] 나간 지시와 관측을 이을 수 없다 — 저장소에 byDispatchRef 나 recordEffects 가 없다. ' +
+            '넘긴 조치가 저쪽에서 무엇이 되었는지 알 수 없는 상태다.');
+        return none;
+    }
+    try {
+        const byRef = await store.byDispatchRef(domainId, (0, effect_match_js_1.refsToLookUp)(observations));
+        if (!byRef.size)
+            return { recorded: 0, unmatched: observations.length };
+        const { updates, skips } = (0, effect_match_js_1.matchEffects)({
+            observations,
+            byRef: new Map([...byRef].map(([ref, c]) => [ref, { id: c.id, dispatchRef: ref, ...(c.effect ? { effect: c.effect } : {}) }]))
+        });
+        if (updates.length)
+            await store.recordEffects(domainId, updates);
+        return { recorded: updates.length, unmatched: skips.length };
+    }
+    catch (e) {
+        /* 관측 유입을 멈추지 않는다 — 위 §. 다만 조용히 넘기지도 않는다. */
+        (0, log_js_1.twinWarn)(`[actuation] 효과를 잇다 실패했다 — ${String(e?.message ?? e).slice(0, 200)}`);
+        return none;
+    }
+}
+//# sourceMappingURL=settle-effects.js.map

package/dist-server/service/actuation/settle-effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle-effects.js","sourceRoot":"","sources":["../../../server/service/actuation/settle-effects.ts"],"names":[],"mappings":";;AA6CA,kDAaC;AAeD,sCAyCC;AAlHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wDAAgD;AAEhD,gDAA8C;AAG9C,uDAAqF;AAErF,wCAAwC;AACxC,SAAgB,mBAAmB,CAAC,SAAyB;IAC3D,MAAM,GAAG,GAAuB,EAAE,CAAA;IAClC,KAAK,MAAM,CAAC,IAAI,SAAS,IAAI,EAAE,EAAE,CAAC;QAChC,IAAI,CAAC,EAAE,SAAS,KAAK,uBAAQ,CAAC,KAAK;YAAE,SAAQ;QAC7C,MAAM,IAAI,GAAG,CAAC,EAAE,IAAI,CAAA;QACpB,IAAI,CAAC,IAAI,EAAE,OAAO;YAAE,SAAQ;QAC5B;;;WAGG;QACH,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAA;IAClG,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AASD;;;;;GAKG;AACI,KAAK,UAAU,aAAa,CAAC,IAInC;IACC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IAC3C,MAAM,IAAI,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAA;IAE1C,MAAM,YAAY,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAA;IACnD,IAAI,CAAC,YAAY,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAErC;;;OAGG;IACH,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;QACjD,IAAA,iBAAQ,EACN,4EAA4E;YAC1E,kCAAkC,CACrC,CAAA;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAA,8BAAY,EAAC,YAAY,CAAC,CAAC,CAAA;QAC7E,IAAI,CAAC,KAAK,CAAC,IAAI;YAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,YAAY,CAAC,MAAM,EAAE,CAAA;QAEvE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,IAAA,8BAAY,EAAC;YACtC,YAAY;YACZ,KAAK,EAAE,IAAI,GAAG,CACZ,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAC/G;SACF,CAAC,CAAA;QAEF,IAAI,OAAO,CAAC,MAAM;YAAE,MAAM,KAAK,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;QAChE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,CAAA;IAC9D,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QAChB,4CAA4C;QAC5C,IAAA,iBAAQ,EAAC,6BAA6B,MAAM,CAAC,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;QAC9E,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC","sourcesContent":["/*\n * **관측이 들어올 때 나간 지시와 잇는다** — 폐루프의 배선. 판단은 `effect-match.ts` 가 한다.\n *\n * ── 무엇이 실측으로 확인됐나 (2026-09-02) ─────────────────────────────────────\n * 인티그레이션 레인이 조치 둘을 MES 까지 걸었다. 트윈 쪽 두 행이 **구별되지 않았다.**\n *\n *   325e9bb1  acked  WO-20260902-004  지시서 붙음      MES 에서 DRAFT\n *   57428362  acked  WO-20260902-005  지시서 못 붙음   MES 에서 DRAFT\n *\n * `state`·`dispatch_ref`·`error` 가 셋 다 같다. 그래서 화면은 둘 다 「나갔다」로 읽는데, 둘 다 아직\n * 현장에 안 갔다. `acked` 의 뜻은 **「저쪽이 받았다」**까지다.\n *\n * 빠져나오는 것은 관측이다 — 저쪽이 그 오더를 현장에 내면 `order.status` 가 우리가 받은 식별자로\n * 돌아온다. 그것을 이 파일이 잇는다.\n *\n * ── 왜 유입 자리인가 ─────────────────────────────────────────────────────────\n * 관측의 **시각**이 봉투에만 있다. 나중에 커널 상태에서 읽으면 「지금」밖에 알 수 없고, 그것은 보고된\n * 시각이 아니라 우리가 처리한 시각이다. 없는 사실을 만들지 않는다.\n *\n * ── 어디서 부르나 ───────────────────────────────────────────────────────────\n *\n *   routes.ts            훅으로 밀려 들어온 것\n *   reference-live.ts    커넥터가 이어 내는 것 · 폴링으로 물어 온 것\n *\n * **백필(`backfill-period-facts.ts`)에서는 부르지 않는다.** 그것은 마감된 구간의 저널을 채우는\n * 일이고, 이 자리가 답하는 것은 「방금 보낸 지시가 어떻게 됐나」다. 저널을 고치는 작업이 조치 기록을\n * 바꾸게 두면, 백필을 다시 돌릴 때마다 같은 보고가 다시 세어진다(`seen` 이 는다).\n *\n * 그래서 지난 기록에서 효과가 확인되는 경우는 지금 다루지 않는다. 필요해지면 그때는 **백필 전용\n * 경로**로 만들 일이다 — 몇 번 세었나가 아니라 「그때 이랬다」만 적는 자리다.\n *\n * ── 값은 얼마나 드나 ─────────────────────────────────────────────────────────\n * 오더 보고가 든 묶음마다 질의 하나다. 조치가 하나도 안 나간 도메인에서도 그 질의가 돈다 — 지금\n * 규모에서 그 값은 작지만 공짜라고 말하지 않는다. 더 줄이려면 「효과를 기다리는 식별자」를 프로세스가\n * 들고 있어야 하고, 그러면 재기동 때 저장소에서 되세우는 자리가 하나 더 생긴다. 그것이 필요해지는\n * 시점은 **오더 보고가 초당 수백 건 오는 도메인**이다.\n */\nimport { OP_EVENT } from '@operato/ops-contract'\n\nimport { twinWarn } from '../../engine/log.js'\n\nimport type { CommandStore } from './command-dispatcher.js'\nimport { matchEffects, refsToLookUp, type OrderObservation } from './effect-match.js'\n\n/** 봉투에서 오더 보고만 골라낸다 — 다른 어휘는 보지 않는다. */\nexport function orderObservationsIn(envelopes: readonly any[]): OrderObservation[] {\n  const out: OrderObservation[] = []\n  for (const e of envelopes ?? []) {\n    if (e?.eventType !== OP_EVENT.order) continue\n    const data = e?.data\n    if (!data?.orderId) continue\n    /*\n     * 시각은 **봉투의 것**을 쓴다. 보고한 쪽이 말한 시각이고, 우리가 처리한 시각이 아니다.\n     * 없으면 `matchEffects` 가 거른다 — 여기서 「지금」으로 채우지 않는다.\n     */\n    out.push({ orderId: String(data.orderId), status: String(data.status ?? ''), at: e?.eventTime })\n  }\n  return out\n}\n\nexport interface SettleEffectsResult {\n  /** 효과를 적은 조치 수. */\n  recorded: number\n  /** 이을 수 없던 보고 수 — 대개 우리가 내지 않은 오더다. */\n  unmatched: number\n}\n\n/**\n * 이 묶음의 오더 보고를 나간 지시와 잇는다 — **아무것도 못 이어도 조용히 지난다.**\n *\n * 유입 경로에서 부른다. 그래서 **던지지 않는다** — 효과를 적다 실패해서 관측 유입이 멈추면, 고치는\n * 동안 트윈이 눈을 감는다. 효과는 다음 보고에 다시 이을 수 있고 관측은 다시 오지 않는다.\n */\nexport async function settleEffects(args: {\n  domainId: string\n  envelopes: readonly any[]\n  store: CommandStore\n}): Promise<SettleEffectsResult> {\n  const { domainId, envelopes, store } = args\n  const none = { recorded: 0, unmatched: 0 }\n\n  const observations = orderObservationsIn(envelopes)\n  if (!observations.length) return none\n\n  /*\n   * 저장소가 두 자리를 안 갖추면 이을 길이 없다. **조용히 지나지 않고 말한다** — 이 상태에서는\n   * 넘긴 지시가 저쪽에서 어떻게 됐는지 영원히 모르고, 화면은 그 사실을 알 수 없다.\n   */\n  if (!store.byDispatchRef || !store.recordEffects) {\n    twinWarn(\n      '[actuation] 나간 지시와 관측을 이을 수 없다 — 저장소에 byDispatchRef 나 recordEffects 가 없다. ' +\n        '넘긴 조치가 저쪽에서 무엇이 되었는지 알 수 없는 상태다.'\n    )\n    return none\n  }\n\n  try {\n    const byRef = await store.byDispatchRef(domainId, refsToLookUp(observations))\n    if (!byRef.size) return { recorded: 0, unmatched: observations.length }\n\n    const { updates, skips } = matchEffects({\n      observations,\n      byRef: new Map(\n        [...byRef].map(([ref, c]) => [ref, { id: c.id, dispatchRef: ref, ...(c.effect ? { effect: c.effect } : {}) }])\n      )\n    })\n\n    if (updates.length) await store.recordEffects(domainId, updates)\n    return { recorded: updates.length, unmatched: skips.length }\n  } catch (e: any) {\n    /* 관측 유입을 멈추지 않는다 — 위 §. 다만 조용히 넘기지도 않는다. */\n    twinWarn(`[actuation] 효과를 잇다 실패했다 — ${String(e?.message ?? e).slice(0, 200)}`)\n    return none\n  }\n}\n"]}

package/dist-server/service/actuation/sweep-dispatch.d.ts

@@ -0,0 +1,37 @@
+import { type ApprovedCommand } from '@operato/ops-contract';
+import { type CommandAck, type CommandStore } from './command-dispatcher.js';
+/** 한 바퀴에 볼 최대 수 — 대기 줄이 커도 한 주기를 독차지하지 않게. */
+export declare const SWEEP_LIMIT = 50;
+export interface SweepReport {
+    /** 표에서 읽은 수. */
+    seen: number;
+    /** 실제로 넘긴 수. */
+    dispatched: number;
+    /** 넘기지 않은 이유별 수 — 목록이 그대로 보인다. */
+    skipped: Record<string, number>;
+}
+/**
+ * 이 테넌트의 대기 줄을 한 바퀴 훑는다.
+ *
+ * 저장소가 대기 줄을 못 내면 **아무것도 하지 않는다** — 그 능력이 없는 구현도 그대로 돌아야
+ * 한다(옛 거동).
+ */
+export interface SweepDeps {
+    store: CommandStore;
+    /** 이 조치를 저쪽에 낸다 — 부르는 쪽이 커넥터 배선을 안다. */
+    actuate: (command: ApprovedCommand) => Promise<CommandAck>;
+    /** 이 연결이 두 번 보내도 지시가 하나인가 — **선언만 참으로 읽는다.** */
+    idempotent: (instanceId: string) => Promise<boolean>;
+    /**
+     * 우리 쪽 설정만으로 답할 수 있는 준비 상태. 저쪽을 두드리지 않는 답만 준다.
+     *
+     * 없으면 앞점검을 하지 않는다(그냥 넘긴다) — 모르는 것을 거절로 접지 않는 규율이다.
+     */
+    localReadiness?: (instanceId: string) => Promise<{
+        ready?: boolean;
+        reason?: string;
+        code?: string;
+    } | undefined>;
+    nowMs?: () => number;
+}
+export declare function sweepPendingDispatch(domainId: string, deps: SweepDeps): Promise<SweepReport>;

package/dist-server/service/actuation/sweep-dispatch.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SWEEP_LIMIT = void 0;
+exports.sweepPendingDispatch = sweepPendingDispatch;
+/*
+ * **남은 것을 줍는 그물** — 승인은 됐는데 안 나간 것, 실패해서 다시 해 볼 것.
+ *
+ * ── 왜 필요한가 (2026-09-04) ────────────────────────────────────────────────
+ * 승인 직후에 한 번 보내는 것만 있었다(§`dispatchAfterApproval`). 정상 경로는 그것으로 282ms 에
+ * 끝난다 — 실측이다. 그런데 두 자리가 비어 있었다.
+ *
+ *   커밋과 발신 사이에 프로세스가 죽으면   그 조치는 `approved` 로 남고 스스로 안 나간다
+ *   실패한 것을 다시 보내려면             사람이 시켜야 했다
+ *
+ * 2026-09-02 에 뒤엣것을 겪었다: 저쪽 인증 정보가 채워진 뒤 사람이 손으로 다시 넘겨서 나갔다.
+ *
+ * ── 왜 새 타이머를 세우지 않나 ──────────────────────────────────────────────
+ * 규칙 주기(`rule-loop`)에 얹는다. 그 파일이 이미 그 이유를 적어 두었다 — 「타이머를 둘 두면
+ * 내리고 세울 자리가 둘이 된다」. 놓친 보고를 backfill 하는 것(`catchUpEffects`)도 같은 자리에 있다.
+ *
+ * 30초면 충분하다. **아무도 안 기다린다** — 정상 경로가 이미 끝냈고, 이 그물은 남은 것만 본다.
+ *
+ * ── 판단은 여기 없다 ────────────────────────────────────────────────────────
+ * 「지금 넘길 것인가, 다음은 언제인가」는 순수 함수가 답한다(§`retryDecisionOf`). 이 파일은
+ * 표를 읽고 그 답대로 하고 결과를 적는 배선이다. 그렇게 갈라 둔 이유는 물러섬 규칙을 30분
+ * 기다리지 않고 값으로 잴 수 있어야 하기 때문이다.
+ *
+ * ── 던지지 않는다 ───────────────────────────────────────────────────────────
+ * 주기 안에서 돈다. 한 조치가 터져도 다음 조치를 봐야 하고, 이 그물이 터져도 규칙과 backfill 은
+ * 돌아야 한다. 조치를 못 넘기는 것과 트윈이 멈추는 것은 다른 사고다.
+ */
+const ops_contract_1 = require("@operato/ops-contract");
+const log_js_1 = require("../../engine/log.js");
+const command_dispatcher_js_1 = require("./command-dispatcher.js");
+const retry_plan_js_1 = require("./retry-plan.js");
+/*
+ * **의존을 인자로 받는다** — 이 파일이 커넥터 등록소·연결 표를 직접 부르지 않는다.
+ *
+ * 규칙 실행이 이미 그 모양이다(`runRulesOnce({ store, rulesOf, attentionsOf … })`). 그렇게 두는
+ * 값이 둘이다: 배선을 시험이 굴릴 수 있고(직접 부르면 시험이 DB·모듈 부팅을 끌어온다 — 실제로
+ * 그렇게 났다), 그리고 이 파일이 무엇에 의존하는지가 서명에 적힌다.
+ */
+/** 한 바퀴에 볼 최대 수 — 대기 줄이 커도 한 주기를 독차지하지 않게. */
+exports.SWEEP_LIMIT = 50;
+async function sweepPendingDispatch(domainId, deps) {
+    const { store } = deps;
+    const now = deps.nowMs ?? (() => Date.now());
+    const report = { seen: 0, dispatched: 0, skipped: {} };
+    if (!store.pendingDispatch)
+        return report;
+    const pending = await store.pendingDispatch(domainId).catch(() => []);
+    report.seen = pending.length;
+    const note = (why) => {
+        report.skipped[why] = (report.skipped[why] ?? 0) + 1;
+    };
+    for (const command of pending.slice(0, exports.SWEEP_LIMIT)) {
+        try {
+            const decision = (0, retry_plan_js_1.retryDecisionOf)({
+                state: command.state,
+                dispatchable: (0, ops_contract_1.nextCommandState)(command.state, 'dispatch') !== undefined,
+                retry: command.retry,
+                attempts: command.attempts,
+                nextAttemptAt: command.nextAttemptAt,
+                idempotent: await deps.idempotent(command.instanceId).catch(() => false),
+                nowMs: now()
+            });
+            if (!decision.take) {
+                note(decision.skip ?? 'unknown');
+                continue;
+            }
+            /*
+             * **넘기기 전에 우리 설정을 먼저 본다** — 아끼려는 것이 아니라 **이유를 지금 값으로
+             * 적으려는** 것이다(인티그레이션 레인이 제 첫 근거를 깼다: 그쪽 어댑터는 이미 `fetch` 전에
+             * 되돌아오므로 아낄 요청이 없다).
+             *
+             * 건너뛰면서 아무것도 안 적으면 **옛 `error` 가 남는다.** 저쪽 인증 정보 때문에 실패해 앉은
+             * 뒤 우리 쪽 설정이 지워지면, 목록에 계속 저쪽 얘기가 보이고 사람이 남의 서버를 보러 간다.
+             *
+             * 모르면(`undefined`) 그냥 넘긴다 — 모르는 것을 거절로 접지 않는다.
+             */
+            const readiness = await deps.localReadiness?.(command.instanceId).catch(() => undefined);
+            if (readiness && readiness.ready === false) {
+                await noteBlocked(store, domainId, command, decision.nextAttemptAt, readiness.reason, readiness.code);
+                note('not-ready');
+                continue;
+            }
+            const settled = await (0, command_dispatcher_js_1.dispatch)(store, domainId, command.id, c => deps.actuate(c));
+            await recordAttempt(store, domainId, settled, decision.attempt ?? 1, decision.nextAttemptAt);
+            if (settled.state === 'failed') {
+                note('failed');
+                (0, log_js_1.twinWarn)(`[twin-sweep] 조치 ${command.id} 를 넘기지 못했다: ${settled.error ?? '(사유 없음)'}`);
+            }
+            else {
+                report.dispatched++;
+            }
+        }
+        catch (e) {
+            /* 한 조치가 터져도 다음을 본다 — 가장 흔한 원인은 그 사이에 상태가 바뀐 것이다. */
+            note('threw');
+            (0, log_js_1.twinWarn)(`[twin-sweep] 조치 ${command.id} 에서 예외 — ${String(e?.message ?? e)}`);
+        }
+    }
+    return report;
+}
+/**
+ * 못 나가는 이유를 **지금 값으로** 적는다 — 넘기지 않았으므로 상태는 그대로다.
+ *
+ * **바뀌었을 때만 쓴다.** 10분마다 같은 이유를 다시 쓰면 `updatedAt` 이 계속 튀고, 목록의
+ * 「언제부터 이랬나」가 사라진다(§`catch-up-effects` 에서 같은 규율을 지켰다).
+ */
+async function noteBlocked(store, domainId, command, nextAttemptAt, reason, code) {
+    const sentence = reason ?? code ?? '연결 설정이 조치를 낼 준비가 되지 않았습니다';
+    if (command.error === sentence && command.nextAttemptAt === nextAttemptAt)
+        return;
+    await store
+        .save(domainId, { ...command, error: sentence, ...(nextAttemptAt ? { nextAttemptAt } : {}) })
+        .catch(err => (0, log_js_1.twinWarn)(`[twin-sweep] 조치 ${command.id} 의 사유를 적지 못했다 — ${String(err?.message ?? err)}`));
+}
+/** 시도 횟수와 다음 시각을 적는다 — `dispatch` 가 쓴 상태를 덮지 않고 이 둘만 더한다. */
+async function recordAttempt(store, domainId, settled, attempt, nextAttemptAt) {
+    await store
+        .save(domainId, { ...settled, attempts: attempt, ...(nextAttemptAt ? { nextAttemptAt } : {}) })
+        .catch(err => (0, log_js_1.twinWarn)(`[twin-sweep] 조치 ${settled.id} 의 시도 기록을 적지 못했다 — ${String(err?.message ?? err)}`));
+}
+//# sourceMappingURL=sweep-dispatch.js.map

package/dist-server/service/actuation/sweep-dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep-dispatch.js","sourceRoot":"","sources":["../../../server/service/actuation/sweep-dispatch.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * **남은 것을 줍는 그물** — 승인은 됐는데 안 나간 것, 실패해서 다시 해 볼 것.\n *\n * ── 왜 필요한가 (2026-09-04) ────────────────────────────────────────────────\n * 승인 직후에 한 번 보내는 것만 있었다(§`dispatchAfterApproval`). 정상 경로는 그것으로 282ms 에\n * 끝난다 — 실측이다. 그런데 두 자리가 비어 있었다.\n *\n *   커밋과 발신 사이에 프로세스가 죽으면   그 조치는 `approved` 로 남고 스스로 안 나간다\n *   실패한 것을 다시 보내려면             사람이 시켜야 했다\n *\n * 2026-09-02 에 뒤엣것을 겪었다: 저쪽 인증 정보가 채워진 뒤 사람이 손으로 다시 넘겨서 나갔다.\n *\n * ── 왜 새 타이머를 세우지 않나 ──────────────────────────────────────────────\n * 규칙 주기(`rule-loop`)에 얹는다. 그 파일이 이미 그 이유를 적어 두었다 — 「타이머를 둘 두면\n * 내리고 세울 자리가 둘이 된다」. 놓친 보고를 backfill 하는 것(`catchUpEffects`)도 같은 자리에 있다.\n *\n * 30초면 충분하다. **아무도 안 기다린다** — 정상 경로가 이미 끝냈고, 이 그물은 남은 것만 본다.\n *\n * ── 판단은 여기 없다 ────────────────────────────────────────────────────────\n * 「지금 넘길 것인가, 다음은 언제인가」는 순수 함수가 답한다(§`retryDecisionOf`). 이 파일은\n * 표를 읽고 그 답대로 하고 결과를 적는 배선이다. 그렇게 갈라 둔 이유는 물러섬 규칙을 30분\n * 기다리지 않고 값으로 잴 수 있어야 하기 때문이다.\n *\n * ── 던지지 않는다 ───────────────────────────────────────────────────────────\n * 주기 안에서 돈다. 한 조치가 터져도 다음 조치를 봐야 하고, 이 그물이 터져도 규칙과 backfill 은\n * 돌아야 한다. 조치를 못 넘기는 것과 트윈이 멈추는 것은 다른 사고다.\n */\nimport { nextCommandState, type ApprovedCommand } from '@operato/ops-contract'\n\nimport { twinWarn } from '../../engine/log.js'\nimport { dispatch, type CommandAck, type CommandStore, type StoredCommand } from './command-dispatcher.js'\nimport { retryDecisionOf } from './retry-plan.js'\n\n/*\n * **의존을 인자로 받는다** — 이 파일이 커넥터 등록소·연결 표를 직접 부르지 않는다.\n *\n * 규칙 실행이 이미 그 모양이다(`runRulesOnce({ store, rulesOf, attentionsOf … })`). 그렇게 두는\n * 값이 둘이다: 배선을 시험이 굴릴 수 있고(직접 부르면 시험이 DB·모듈 부팅을 끌어온다 — 실제로\n * 그렇게 났다), 그리고 이 파일이 무엇에 의존하는지가 서명에 적힌다.\n */\n\n/** 한 바퀴에 볼 최대 수 — 대기 줄이 커도 한 주기를 독차지하지 않게. */\nexport const SWEEP_LIMIT = 50\n\nexport interface SweepReport {\n  /** 표에서 읽은 수. */\n  seen: number\n  /** 실제로 넘긴 수. */\n  dispatched: number\n  /** 넘기지 않은 이유별 수 — 목록이 그대로 보인다. */\n  skipped: Record<string, number>\n}\n\n/**\n * 이 테넌트의 대기 줄을 한 바퀴 훑는다.\n *\n * 저장소가 대기 줄을 못 내면 **아무것도 하지 않는다** — 그 능력이 없는 구현도 그대로 돌아야\n * 한다(옛 거동).\n */\nexport interface SweepDeps {\n  store: CommandStore\n  /** 이 조치를 저쪽에 낸다 — 부르는 쪽이 커넥터 배선을 안다. */\n  /*\n   * `dispatch` 가 승인 기록을 확인한 뒤의 커맨드를 넘겨 준다(`ApprovedCommand`) — 그 타입을 그대로\n   * 받는다. 우리가 `StoredCommand` 로 넓히면 「승인 없이 나갈 수 있는 서명」이 된다.\n   */\n  actuate: (command: ApprovedCommand) => Promise<CommandAck>\n  /** 이 연결이 두 번 보내도 지시가 하나인가 — **선언만 참으로 읽는다.** */\n  idempotent: (instanceId: string) => Promise<boolean>\n  /**\n   * 우리 쪽 설정만으로 답할 수 있는 준비 상태. 저쪽을 두드리지 않는 답만 준다.\n   *\n   * 없으면 앞점검을 하지 않는다(그냥 넘긴다) — 모르는 것을 거절로 접지 않는 규율이다.\n   */\n  localReadiness?: (instanceId: string) => Promise<{ ready?: boolean; reason?: string; code?: string } | undefined>\n  nowMs?: () => number\n}\n\nexport async function sweepPendingDispatch(domainId: string, deps: SweepDeps): Promise<SweepReport> {\n  const { store } = deps\n  const now = deps.nowMs ?? (() => Date.now())\n  const report: SweepReport = { seen: 0, dispatched: 0, skipped: {} }\n  if (!store.pendingDispatch) return report\n\n  const pending = await store.pendingDispatch(domainId).catch(() => [] as readonly StoredCommand[])\n  report.seen = pending.length\n\n  const note = (why: string) => {\n    report.skipped[why] = (report.skipped[why] ?? 0) + 1\n  }\n\n  for (const command of pending.slice(0, SWEEP_LIMIT)) {\n    try {\n      const decision = retryDecisionOf({\n        state: command.state,\n        dispatchable: nextCommandState(command.state, 'dispatch') !== undefined,\n        retry: command.retry,\n        attempts: command.attempts,\n        nextAttemptAt: command.nextAttemptAt,\n        idempotent: await deps.idempotent(command.instanceId).catch(() => false),\n        nowMs: now()\n      })\n\n      if (!decision.take) {\n        note(decision.skip ?? 'unknown')\n        continue\n      }\n\n      /*\n       * **넘기기 전에 우리 설정을 먼저 본다** — 아끼려는 것이 아니라 **이유를 지금 값으로\n       * 적으려는** 것이다(인티그레이션 레인이 제 첫 근거를 깼다: 그쪽 어댑터는 이미 `fetch` 전에\n       * 되돌아오므로 아낄 요청이 없다).\n       *\n       * 건너뛰면서 아무것도 안 적으면 **옛 `error` 가 남는다.** 저쪽 인증 정보 때문에 실패해 앉은\n       * 뒤 우리 쪽 설정이 지워지면, 목록에 계속 저쪽 얘기가 보이고 사람이 남의 서버를 보러 간다.\n       *\n       * 모르면(`undefined`) 그냥 넘긴다 — 모르는 것을 거절로 접지 않는다.\n       */\n      const readiness = await deps.localReadiness?.(command.instanceId).catch(() => undefined)\n      if (readiness && readiness.ready === false) {\n        await noteBlocked(store, domainId, command, decision.nextAttemptAt, readiness.reason, readiness.code)\n        note('not-ready')\n        continue\n      }\n\n      const settled = await dispatch(store, domainId, command.id, c => deps.actuate(c))\n\n      await recordAttempt(store, domainId, settled, decision.attempt ?? 1, decision.nextAttemptAt)\n\n      if (settled.state === 'failed') {\n        note('failed')\n        twinWarn(`[twin-sweep] 조치 ${command.id} 를 넘기지 못했다: ${settled.error ?? '(사유 없음)'}`)\n      } else {\n        report.dispatched++\n      }\n    } catch (e: any) {\n      /* 한 조치가 터져도 다음을 본다 — 가장 흔한 원인은 그 사이에 상태가 바뀐 것이다. */\n      note('threw')\n      twinWarn(`[twin-sweep] 조치 ${command.id} 에서 예외 — ${String(e?.message ?? e)}`)\n    }\n  }\n\n  return report\n}\n\n/**\n * 못 나가는 이유를 **지금 값으로** 적는다 — 넘기지 않았으므로 상태는 그대로다.\n *\n * **바뀌었을 때만 쓴다.** 10분마다 같은 이유를 다시 쓰면 `updatedAt` 이 계속 튀고, 목록의\n * 「언제부터 이랬나」가 사라진다(§`catch-up-effects` 에서 같은 규율을 지켰다).\n */\nasync function noteBlocked(\n  store: CommandStore,\n  domainId: string,\n  command: StoredCommand,\n  nextAttemptAt: string | undefined,\n  reason?: string,\n  code?: string\n): Promise<void> {\n  const sentence = reason ?? code ?? '연결 설정이 조치를 낼 준비가 되지 않았습니다'\n  if (command.error === sentence && command.nextAttemptAt === nextAttemptAt) return\n\n  await store\n    .save(domainId, { ...command, error: sentence, ...(nextAttemptAt ? { nextAttemptAt } : {}) })\n    .catch(err => twinWarn(`[twin-sweep] 조치 ${command.id} 의 사유를 적지 못했다 — ${String(err?.message ?? err)}`))\n}\n\n/** 시도 횟수와 다음 시각을 적는다 — `dispatch` 가 쓴 상태를 덮지 않고 이 둘만 더한다. */\nasync function recordAttempt(\n  store: CommandStore,\n  domainId: string,\n  settled: StoredCommand,\n  attempt: number,\n  nextAttemptAt: string | undefined\n): Promise<void> {\n  await store\n    .save(domainId, { ...settled, attempts: attempt, ...(nextAttemptAt ? { nextAttemptAt } : {}) })\n    .catch(err => twinWarn(`[twin-sweep] 조치 ${settled.id} 의 시도 기록을 적지 못했다 — ${String(err?.message ?? err)}`))\n}\n"]}

package/dist-server/service/actuation/twin-command-resolver.d.ts

@@ -0,0 +1,120 @@
+import { ListParam } from '@things-factory/shell';
+export declare class TwinCommandResolver {
+    /**
+     * 커맨드 목록 — 기본은 **결정을 기다리는 것부터**.
+     *
+     * 정렬을 최근순으로 두지 않는다. 승인 대기 줄에서 사람이 찾는 것은 「새로 온 것」이 아니라
+     * **「오래 기다린 것」**이다 — 오래 기다린 조치가 뒤로 밀리면 그것이 가장 늦게 처리된다.
+     */
+    twinCommands(params: ListParam, context: ResolverContext): Promise<any>;
+    /**
+     * **이 조치에 대해 트윈이 지금 보는 것과 AI 의견** — 승인 화면이 부른다.
+     *
+     * ── 왜 조회인가 (2026-09-01) ───────────────────────────────────────────
+     * 결재선에 올릴 때 묻지 않는다. 그 자리는 트랜잭션 안이고 거기서 LLM 을 기다리면 DB 연결 하나를 몇 초
+     * 붙잡는다. 그리고 **승인하는 사람은 지금 판단한다** — 올린 시각의 의견은 낡았다.
+     *
+     * AI 는 판정하지 않는다. 이 값을 읽어 승인·거절을 막는 코드가 없다. 반대해도 승인되고 동의해도
+     * 거절된다 — 판정에 쓰면 AI 가 사실상 승인자가 되고, 그러면 사고 뒤에 책임을 물을 자리가 사라진다.
+     */
+    twinActuationOpinion(id: string, 
+    /**
+     * AI 에게도 물을 것인가 — **누르면 묻는다.**
+     *
+     * 기본은 안 묻는다. 화면을 열 때마다 부르면 승인자 다섯 명이 두 번씩 열 때 한 건에 열 번이고,
+     * 대부분의 지시는 평범해서 그중 아홉 번은 같은 말을 다시 받는 것이다.
+     */
+    askAi: boolean, locale: string, context: ResolverContext): Promise<any>;
+    /**
+     * 조치를 낸다 — **대기 줄에 무언가가 들어오는 유일한 자리.**
+     *
+     * 결재선이 등록된 배포에서는 여기서 바로 결재선에 올라간다(§`ApprovalGateway`). 등록되지 않았으면
+     * 제안 상태로 남고, 이 리졸버의 직접 승인이 유일한 문이 된다. 어느 쪽인지는 답에 적어 준다 — 화면이
+     * 「어디서 승인하는가」를 사람에게 말해야 한다.
+     *
+     * 되돌릴 수 있는 조치는 결재선에 올리지 않는다. 계약이 그 판단을 든다(§`requiresApproval`).
+     */
+    proposeTwinCommand(instanceId: string, type: string, payload: any, context: ResolverContext): Promise<any>;
+    /**
+     * **사람이 결재선에 올린다** — 규칙이 낸 조치가 승인 앞에 서는 유일한 길.
+     *
+     * ── 왜 규칙이 직접 올리지 않나 ─────────────────────────────────────────
+     * 업무 목록의 결재선은 **올린 사람 기준**으로 풀린다 — `Myself` · `MyDepartment` · `MySupervisor` 가
+     * 전부 로그인한 사람을 본다. 배경 루프에는 「나」가 없으므로, 시스템 사용자를 지어내 올리면 그 셋이
+     * 시스템 사용자를 가리키고 결재선이 뜻을 잃는다.
+     *
+     * 그래서 규칙은 내는 것까지 하고, 여기서 사람이 올린다. **올린 사람이 「이것을 승인자들 앞에 놓았다」의
+     * 주체**가 되고, 그 사람 기준으로 결재선이 풀린다.
+     *
+     * 올린 사람은 자기가 올린 것을 승인할 수 있다 — 규칙이 낸 조치에는 낸 사람이 없으므로 승인자가 곧
+     * 두 번째 사람이다. 올린 것과 낸 것은 다르다.
+     */
+    raiseTwinCommand(id: string, context: ResolverContext): Promise<any>;
+    /**
+     * 승인한다 — **누가 승인했는지는 로그인한 사람에서 온다.**
+     *
+     * 인자로 받지 않는다. 받으면 다른 사람 이름으로 승인할 수 있고, 그러면 그 기록이 사고 뒤에 쓸 수
+     * 없어진다. 승인 기록의 값어치가 거기서 나온다.
+     */
+    approveTwinCommand(id: string, note: string, context: ResolverContext): Promise<any>;
+    /**
+     * 거절한다 — 여기서 끝난다.
+     *
+     * 사유를 요구한다. 거절은 현장이 기다리던 조치를 취소하는 것이고, 이유 없이 거절되면 낸 쪽이 다시
+     * 낸다. 그러면 같은 것이 대기 줄에 계속 돌아온다.
+     */
+    rejectTwinCommand(id: string, reason: string, context: ResolverContext): Promise<any>;
+    /**
+     * 어댑터에 넘긴다 — **승인을 지나지 않은 것은 여기서 막힌다.**
+     *
+     * ── 이름이 왜 `dispatchTwinCommand` 가 아닌가 (2026-09-01) ─────────────
+     * 그 이름은 이미 **커널 자극**이 쓴다(`TwinControlMutation.dispatchTwinCommand` —
+     * `order.hold`·`resource.repair` 를 커널에 넣는다). 같은 이름을 두 번 선언하면 type-graphql 이
+     * 오류 없이 하나만 남기고, 실제로 이 뮤테이션이 통째로 가려져 있었다 — 걸어 보고 알았다.
+     *
+     * 자극과 조치가 다른 어휘라는 것을 계약에서 갈라 놓고(§`propose` 의 거절), 정작 API 이름에서 겹쳐
+     * 두었다. 여기서는 조치임을 이름에 적는다.
+     *
+     * 화면이 이것을 따로 부르는 이유는, 승인과 넘김이 다른 순간이기 때문이다. 승인한 사람과 넘긴 시각이
+     * 같아야 할 이유가 없고, 어댑터가 죽어 있으면 승인은 남아 있어야 한다.
+     *
+     * ── 여기가 끊겨 있었다 (2026-09-02) ──────────────────────────────────
+     * 이 자리가 **어댑터를 찾지도 않고** 「구현이 없습니다」를 답했다. MES 커넥터는 그때 이미 `actuate`
+     * 를 다 만들어 두었다. 그 답을 사실로 읽어서 설계 문서에도, 다른 레인에도 그렇게 알렸다 — 둘 다
+     * 틀렸다.
+     *
+     * 이제 원본을 찾아 그 원본이 선언한 능력으로 판단한다(§`routeActuation`). 보내지 못하면 **무엇이
+     * 없어서인지** 말한다. 조용히 성공을 답하면 화면은 나간 줄로 읽고, 현장은 오지 않는 지시를 기다린다.
+     *
+     * ── 여기에는 트랜잭션을 걸지 않는다 ──────────────────────────────────
+     * 넘기기 전에 「넘기는 중」을 먼저 적는 것이 이 함수의 요점이다. 한 트랜잭션에 묶으면 그 기록이
+     * 커밋 전까지 아무에게도 보이지 않고, 넘기는 사이에 프로세스가 죽으면 그대로 사라진다. 그러면 저쪽은
+     * 받았는데 우리는 안 보낸 줄 알고 다시 보낸다 — 현장이 두 번 움직인다.
+     */
+    /**
+     * **이 조치를 넘길 수 있나** — 누르기 전에 답한다.
+     *
+     * ── 왜 이 자리가 필요한가 (2026-09-03) ────────────────────────────────────
+     * 판정 함수 둘을 만들어 두고 **부르는 자리를 안 만들었다**(`actuationTargetOf`·
+     * `actuationReadinessOf`). 그래서 화면이 물을 방법이 없었고, 못 넘기는 조치도 눌러 보고 알게 됐다.
+     * 인티그레이션 레인이 그 사실을 두 번 짚어 줬다 — 자리는 있고 길이 없는 그 부류다.
+     *
+     * 그동안 값이 실제로 없어졌다. 저쪽에 비밀값이 없던 날, 사람이 승인 화면까지 가서 누르고 실패를
+     * 보고 다시 로그인했다. **승인은 살아 있지만 사람의 시간은 돌아오지 않는다.**
+     *
+     * ── 둘을 함께 답한다 ──────────────────────────────────────────────────────
+     * 화면이 묻는 것은 하나다 — 「지금 넘겨도 되나」. 그 답이 두 겹이라 둘을 함께 싣는다.
+     *
+     *   target      보낼 대상이 정해지나 — 망을 타지 않는다(원본·능력·사이트)
+     *   readiness   저쪽이 받을 준비가 됐나 — 커넥터가 망을 탈 수 있다
+     *
+     * **문이 아니다.** 이 답으로 넘김을 막지 않는다(§`actuationReadinessOf`) — 화면이 미리 말하는
+     * 데까지다. 그래서 조회이고 뮤테이션이 아니다.
+     *
+     * 화면이 **목록을 그릴 때 부르지 말 것.** 커넥터가 저쪽에 물을 수 있어서 목록 한 줄마다 망을 탄다.
+     * 사람이 「넘기기」를 열 때 한 번이다.
+     */
+    twinActuationReadiness(id: string, context: ResolverContext): Promise<any>;
+    twinActuationOutcome(id: string, context: ResolverContext): Promise<any>;
+    dispatchTwinActuation(id: string, context: ResolverContext): Promise<any>;
+}