@things-factory/headless-twin 10.0.19 → 10.1.0

package/server/service/actuation/rule-runner.ts

@@ -0,0 +1,216 @@
+/*
+ * **규칙을 주기로 돈다** — 판정을 저장소에 잇는 자리.
+ *
+ * ── 왜 틱이 아닌가 (2026-09-01) ──────────────────────────────────────────
+ * 커널 틱 안에 넣으려다 `tickGuarded` 를 읽고 접었다. 그 자리는 **예외가 나면 트윈을 멈추고**, 굶김
+ * 감시가 느린 틱 셋에 트윈을 내린다. 규칙 판정은 DB 를 두 번 건드리므로 그 감시에 정확히 걸린다.
+ *
+ * 그리고 필요하지도 않다. 「병목이 세 시간째」를 1초마다 다시 물을 이유가 없다.
+ *
+ * ── 규칙은 결재선에 올리지 않는다 ────────────────────────────────────────
+ * 이것이 이 파일의 가장 중요한 규율이다.
+ *
+ * 업무 목록의 결재선은 **올린 사람 기준**으로 풀린다 — `Myself` · `MyDepartment` · `MySupervisor` 가
+ * 전부 `context.state.user` 를 본다(§`getSystemUserFromOrgMemberItem`). 배경 루프에는 「나」가 없다.
+ * 시스템 사용자를 지어내 넘기면 그 셋이 **시스템 사용자를 가리키게 되고**, 결재선이 뜻을 잃는다.
+ *
+ * 그래서 규칙은 **내는 것까지** 한다. 결재선에 올리는 것은 사람이 한다(§`raiseTwinCommand`) — 그 사람이
+ * 「이것을 승인자들 앞에 놓았다」의 주체가 되고, 그 사람 기준으로 결재선이 풀린다.
+ *
+ * 올리기 전까지 그 조치는 나가지 못한다. 게이트는 그대로 서 있다.
+ */
+import type { CommandTypeSpec } from '@operato/ops-contract'
+
+import { twinError, twinWarn } from '../../engine/log.js'
+
+import { propose, type CommandStore } from './command-dispatcher.js'
+import { evaluateRules, type ActuationRuleSpec, type AttentionLike, type RuleSkip } from './rule-evaluate.js'
+
+/** 이 프로세스가 든 트윈 하나. */
+export interface OwnedTwin {
+  domainId: string
+  instanceId: string
+}
+
+/** 한 트윈을 돌고 나서 남는 사실. */
+export interface TwinRunReport {
+  domainId: string
+  instanceId: string
+  /** 실제로 적힌 커맨드 수. */
+  proposed: number
+  /** 규칙마다 몇 개를 냈나 — 규칙 행에 누계를 적으려면 나누어 세어야 한다. */
+  proposedByRule: Record<string, number>
+  /** 왜 안 올렸나 — 규칙이 조용히 안 도는 것과 조건이 없어서 안 내는 것을 구별한다. */
+  skips: RuleSkip[]
+  /** 상한에 닿아 두고 온 수. */
+  withheld?: number
+  /** 이 트윈을 아예 못 돌았으면 그 이유. */
+  failed?: string
+}
+
+/** 밖에서 받는 것들 — 저장소도 엔진도 시계도 인자다. 그래야 시험이 재기동과 상한을 걸을 수 있다. */
+export interface RuleRunnerDeps {
+  /** 이 프로세스가 든 트윈들. 남의 프로세스가 든 트윈은 그쪽이 돈다. */
+  ownedTwins(): OwnedTwin[]
+  /** 이 트윈에 걸린 규칙 — 없으면 스냅샷을 읽지 않는다. */
+  rulesOf(twin: OwnedTwin): Promise<ActuationRuleSpec[]>
+  /** 지금 서 있는 주의들. */
+  attentionsOf(twin: OwnedTwin): AttentionLike[] | undefined
+  /**
+   * 이 트윈이 **무엇을 비추고 있나** — 관측(`live`)인가 가정(`sim`)인가.
+   *
+   * 이 값이 없거나 `live` 가 아니면 조치를 내지 않는다(§`runOneTwin`). 모름을 통과로 읽지 않는다.
+   */
+  modeOf(twin: OwnedTwin): 'live' | 'sim' | undefined
+  /** 커맨드가 사는 자리. */
+  store: CommandStore
+  /** 선언된 조치 종류 — 없는 종류를 가리키는 규칙은 판정이 걸러 낸다. */
+  specs: readonly CommandTypeSpec[]
+  nowMs(): number
+  /** 돈 결과를 규칙 행에 남긴다 — 화면이 「이 규칙이 돌고 있나」를 말할 수 있게. */
+  noteRun?(twin: OwnedTwin, report: TwinRunReport): Promise<void>
+  maxPerRun?: number
+}
+
+/**
+ * 한 바퀴 돈다 — **한 트윈이 실패해도 나머지는 돈다.**
+ *
+ * 트윈 하나의 규칙이 잘못됐다고 다른 공장의 규칙이 멈추면, 고치는 동안 전체가 멈춘 셈이 된다.
+ */
+export async function runRulesOnce(deps: RuleRunnerDeps): Promise<TwinRunReport[]> {
+  const out: TwinRunReport[] = []
+
+  for (const twin of deps.ownedTwins()) {
+    const report: TwinRunReport = { ...twin, proposed: 0, proposedByRule: {}, skips: [] }
+    try {
+      Object.assign(report, await runOneTwin(twin, deps))
+    } catch (e: any) {
+      report.failed = String(e?.message ?? e)
+      twinError(`[twin-rule] "${twin.instanceId}" 규칙을 돌지 못했다 — ${report.failed}`)
+    }
+    out.push(report)
+
+    if (deps.noteRun) {
+      await deps.noteRun(twin, report).catch(err =>
+        twinWarn(`[twin-rule] "${twin.instanceId}" 규칙 기록을 남기지 못했다 — ${err?.message ?? err}`)
+      )
+    }
+  }
+
+  return out
+}
+
+async function runOneTwin(twin: OwnedTwin, deps: RuleRunnerDeps): Promise<Partial<TwinRunReport>> {
+  const rules = await deps.rulesOf(twin)
+  /* 규칙이 없으면 스냅샷도 읽지 않는다 — 아무것도 안 할 일에 값을 만들지 않는다. */
+  if (!rules.length) return {}
+
+  /*
+   * **이미 올라가 있는 근거를 저장소에서 읽는다.**
+   *
+   * 저장소가 그 길을 내주지 않으면 **판정하지 않는다.** 빈 집합을 만들어 주면 매 주기 같은 조건이 다시
+   * 올라가 대기 줄에 같은 지시가 쌓인다 — 그것을 조용히 하지 않는다.
+   */
+  if (!deps.store.openCauses) {
+    return {
+      skips: [
+        {
+          ruleId: '(전체)',
+          reason:
+            '이 저장소는 이미 올라간 근거를 말해 주지 않는다 — 판정하면 같은 조건이 주기마다 다시 올라간다. ' +
+            'CommandStore.openCauses 가 필요하다'
+        }
+      ]
+    }
+  }
+
+  /*
+   * ── **시늉된 조건에서 현장 지시를 내지 않는다** (2026-09-01) ────────────
+   *
+   * 시뮬 트윈의 상태는 **가정**이다. 커널이 스스로 물품을 옮겨 만든 병목이고, 현장에서 관측된 것이
+   * 아니다. 그 위에서 생산 지시를 내면 **지어낸 조건이 실제 지시가 된다** — 오늘 자극과 조치를 갈라
+   * 놓은 것과 같은 부류의 잘못이고, 이쪽이 더 나쁘다(자극은 모델 안에서 끝나지만 이것은 현장으로 나간다).
+   *
+   * 실제로 그렇게 걸었다. 오늘 규칙을 확인한 트윈이 전부 `sim` 이었고, 시늉된 병목에서 생산 지시가
+   * 올라왔다. 배선은 옳게 돌았지만 근거는 가정이었다.
+   *
+   * 예측을 근거로 미리 지시를 내는 것 자체는 있을 수 있는 일이다. 다만 그것은 **선언해서** 할 일이고,
+   * 승인하는 사람이 「이것은 예측이다」를 알아야 한다. 그 선언이 아직 없으므로 지금은 막고, 왜 막았는지
+   * 말한다 — 그 문장이 필요해진 사람이 무엇을 요청해야 하는지 알려 준다.
+   */
+  const mode = deps.modeOf(twin)
+  if (mode !== 'live') {
+    return {
+      skips: [
+        {
+          ruleId: '(전체)',
+          reason:
+            mode === 'sim'
+              ? '이 트윈은 시뮬레이션이다 — 시늉된 조건에서 현장 지시를 내지 않는다. ' +
+                '예측을 근거로 미리 내려면 그것을 선언하는 자리가 필요하고, 아직 없다'
+              : '이 트윈이 관측을 비추는지 알 수 없다 — 모름을 「관측이다」로 읽지 않는다'
+        }
+      ]
+    }
+  }
+
+  const attentions = deps.attentionsOf(twin)
+  if (attentions === undefined) {
+    /*
+     * 스냅샷이 없다 — 멈춘 트윈이거나 아직 안 선 트윈이다. **주의가 0건인 것과 다르다.** 0건으로 읽으면
+     * 「조건이 하나도 없다」가 되고, 규칙이 도는 줄로 보인다.
+     */
+    return {
+      skips: [{ ruleId: '(전체)', reason: '이 트윈의 상태를 읽을 수 없다 — 멈춰 있거나 아직 서지 않았다' }]
+    }
+  }
+
+  const openCauses = await deps.store.openCauses(twin.domainId, twin.instanceId)
+  /* 없으면 넘기지 않는다 — 판정이 「받지 못했다」와 「낸 적이 없다」를 구별해야 한다. */
+  const lastProposedAt = await deps.store.lastProposedAt?.(twin.domainId, twin.instanceId)
+
+  const verdict = evaluateRules({
+    rules,
+    attentions,
+    specs: deps.specs,
+    openCauses,
+    ...(lastProposedAt ? { lastProposedAt } : {}),
+    nowMs: deps.nowMs(),
+    ...(deps.maxPerRun ? { maxPerRun: deps.maxPerRun } : {})
+  })
+
+  const skips = [...verdict.skips]
+  const proposedByRule: Record<string, number> = {}
+  let proposed = 0
+
+  for (const p of verdict.proposals) {
+    try {
+      await propose(deps.store, twin.domainId, deps.specs, {
+        id: newCommandId(),
+        instanceId: twin.instanceId,
+        type: p.commandType,
+        /* 사람이 아니다. 그래서 낸 사람이 없고, 아무 승인자든 두 번째 사람이 된다. */
+        origin: 'rule',
+        proposedAt: new Date(deps.nowMs()).toISOString(),
+        payload: p.payload,
+        causeRef: p.attentionId,
+        ruleRef: p.ruleId
+      })
+      proposed++
+      proposedByRule[p.ruleId] = (proposedByRule[p.ruleId] ?? 0) + 1
+    } catch (e: any) {
+      /*
+       * 하나가 거절돼도 나머지는 낸다. 그리고 **거절을 삼키지 않는다** — 규칙이 무언가를 내려 했는데
+       * 못 냈다는 사실이 사라지면, 사람은 그 조건에 규칙이 안 걸린 줄로 읽는다.
+       */
+      skips.push({ ruleId: p.ruleId, attentionId: p.attentionId, reason: String(e?.message ?? e) })
+    }
+  }
+
+  return { proposed, proposedByRule, skips, ...(verdict.withheld ? { withheld: verdict.withheld } : {}) }
+}
+
+/** 식별자 — 이 파일이 만든다. 저장소가 만들면 커맨드를 적기 전에 근거를 붙일 수 없다. */
+function newCommandId(): string {
+  return globalThis.crypto.randomUUID()
+}

package/server/service/actuation/rule-wiring.ts

@@ -0,0 +1,84 @@
+/*
+ * 규칙 판정이 **실제 엔진·저장소에 닿는 자리** — 한 벌.
+ *
+ * 리졸버(「지금 돌려 본다」)와 주기 루프가 같은 배선을 써야 한다. 두 벌이면 화면에서 돌려 봤을 때와
+ * 주기가 돌 때가 다르게 동작하고, 사람은 「돌려 봤을 때는 됐는데」를 겪는다.
+ */
+import { TwinEngine } from '../../engine/twin-engine.js'
+import { getRepository } from '@things-factory/shell'
+
+import { TwinActuationRule } from './actuation-rule.js'
+import type { ActuationRuleSpec, AttentionLike } from './rule-evaluate.js'
+import type { OwnedTwin, TwinRunReport } from './rule-runner.js'
+
+/** 이 트윈에 걸린 규칙 — 꺼 둔 것도 함께 준다(판정이 거른다. 「꺼져 있다」는 판정의 규율이다). */
+export async function rulesOf(twin: OwnedTwin): Promise<ActuationRuleSpec[]> {
+  const rows = await getRepository(TwinActuationRule).find({
+    where: { domain: { id: twin.domainId }, instanceId: twin.instanceId }
+  })
+
+  return rows.map(r => ({
+    id: r.id,
+    instanceId: r.instanceId,
+    attentionKind: r.attentionKind,
+    ...(r.minSeverity ? { minSeverity: r.minSeverity as any } : {}),
+    ...(r.minHeldMs ? { minHeldMs: r.minHeldMs } : {}),
+    ...(r.cooldownMs === null || r.cooldownMs === undefined ? {} : { cooldownMs: r.cooldownMs }),
+    commandType: r.commandType,
+    ...(r.payloadTemplate ? { payloadTemplate: r.payloadTemplate } : {}),
+    enabled: r.enabled !== false
+  }))
+}
+
+/**
+ * 이 트윈이 관측을 비추나 가정을 돌리나 — 조치를 낼 수 있는지가 여기서 갈린다.
+ *
+ * 판정과 같은 술어를 쓴다(`TwinEngine.modeOf`). 두 벌이면 어긋난다.
+ */
+export function modeOf(twin: OwnedTwin): 'live' | 'sim' | undefined {
+  return TwinEngine.modeOf(twin.domainId, twin.instanceId)
+}
+
+/**
+ * 지금 서 있는 주의들 — **못 읽으면 `undefined`.**
+ *
+ * 빈 배열로 답하지 않는다. 멈춘 트윈을 「조건이 하나도 없다」로 읽으면 규칙이 도는 줄로 보인다.
+ * 주의 질의와 같은 원천을 쓴다(§`twin-attention-query.ts`) — 두 곳이 다른 것을 보면 화면에 보이는
+ * 조건과 규칙이 보는 조건이 어긋난다.
+ */
+export function attentionsOf(twin: OwnedTwin): AttentionLike[] | undefined {
+  if (!TwinEngine.owns(twin.domainId, twin.instanceId)) return undefined
+
+  const kernel = TwinEngine.kernel(twin.domainId, twin.instanceId)
+  const snap = kernel?.getSnapshot?.() ?? TwinEngine.snapshot(twin.domainId, twin.instanceId)
+  if (!snap) return undefined
+
+  return (snap.attentions ?? []) as AttentionLike[]
+}
+
+/**
+ * 돈 결과를 규칙 행에 남긴다 — **조용히 안 도는 규칙과 조건이 없어서 안 내는 규칙을 구별하려면 필요하다.**
+ *
+ * 이 트윈의 모든 규칙에 `lastRunAt` 을 찍는다. 이유는 그 규칙 것만 적는다.
+ */
+export async function noteRun(twin: OwnedTwin, report: TwinRunReport): Promise<void> {
+  const repo = getRepository(TwinActuationRule)
+  const rows = await repo.find({ where: { domain: { id: twin.domainId }, instanceId: twin.instanceId } })
+  if (!rows.length) return
+
+  const at = new Date().toISOString()
+  const reasonOf = (id: string) => report.skips.filter(s => s.ruleId === id).map(s => s.reason)[0] ?? null
+
+  await repo.save(
+    rows.map(row => ({
+      ...row,
+      lastRunAt: at,
+      proposedCount: (row.proposedCount ?? 0) + (report.proposedByRule[row.id] ?? 0),
+      /*
+       * 이유는 그 규칙 것만 적는다. 트윈 전체가 못 돈 경우(§`failed`)는 모든 규칙에 같은 이유가 붙는다
+       * — 그때는 규칙 하나의 문제가 아니기 때문이다.
+       */
+      lastSkipReason: report.failed ?? reasonOf(row.id)
+    })) as any
+  )
+}

package/server/service/actuation/settle-effects.ts

@@ -0,0 +1,115 @@
+/*
+ * **관측이 들어올 때 나간 지시와 잇는다** — 폐루프의 배선. 판단은 `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` 이 는다).
+ *
+ * 그래서 지난 기록에서 효과가 확인되는 경우는 지금 다루지 않는다. 필요해지면 그때는 **백필 전용
+ * 경로**로 만들 일이다 — 몇 번 세었나가 아니라 「그때 이랬다」만 적는 자리다.
+ *
+ * ── 값은 얼마나 드나 ─────────────────────────────────────────────────────────
+ * 오더 보고가 든 묶음마다 질의 하나다. 조치가 하나도 안 나간 도메인에서도 그 질의가 돈다 — 지금
+ * 규모에서 그 값은 작지만 공짜라고 말하지 않는다. 더 줄이려면 「효과를 기다리는 식별자」를 프로세스가
+ * 들고 있어야 하고, 그러면 재기동 때 저장소에서 되세우는 자리가 하나 더 생긴다. 그것이 필요해지는
+ * 시점은 **오더 보고가 초당 수백 건 오는 도메인**이다.
+ */
+import { OP_EVENT } from '@operato/ops-contract'
+
+import { twinWarn } from '../../engine/log.js'
+
+import type { CommandStore } from './command-dispatcher.js'
+import { matchEffects, refsToLookUp, type OrderObservation } from './effect-match.js'
+
+/** 봉투에서 오더 보고만 골라낸다 — 다른 어휘는 보지 않는다. */
+export function orderObservationsIn(envelopes: readonly any[]): OrderObservation[] {
+  const out: OrderObservation[] = []
+  for (const e of envelopes ?? []) {
+    if (e?.eventType !== 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
+}
+
+export interface SettleEffectsResult {
+  /** 효과를 적은 조치 수. */
+  recorded: number
+  /** 이을 수 없던 보고 수 — 대개 우리가 내지 않은 오더다. */
+  unmatched: number
+}
+
+/**
+ * 이 묶음의 오더 보고를 나간 지시와 잇는다 — **아무것도 못 이어도 조용히 지난다.**
+ *
+ * 유입 경로에서 부른다. 그래서 **던지지 않는다** — 효과를 적다 실패해서 관측 유입이 멈추면, 고치는
+ * 동안 트윈이 눈을 감는다. 효과는 다음 보고에 다시 이을 수 있고 관측은 다시 오지 않는다.
+ */
+export async function settleEffects(args: {
+  domainId: string
+  envelopes: readonly any[]
+  store: CommandStore
+}): Promise<SettleEffectsResult> {
+  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) {
+    twinWarn(
+      '[actuation] 나간 지시와 관측을 이을 수 없다 — 저장소에 byDispatchRef 나 recordEffects 가 없다. ' +
+        '넘긴 조치가 저쪽에서 무엇이 되었는지 알 수 없는 상태다.'
+    )
+    return none
+  }
+
+  try {
+    const byRef = await store.byDispatchRef(domainId, refsToLookUp(observations))
+    if (!byRef.size) return { recorded: 0, unmatched: observations.length }
+
+    const { updates, skips } = 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: any) {
+    /* 관측 유입을 멈추지 않는다 — 위 §. 다만 조용히 넘기지도 않는다. */
+    twinWarn(`[actuation] 효과를 잇다 실패했다 — ${String(e?.message ?? e).slice(0, 200)}`)
+    return none
+  }
+}

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

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