@things-factory/headless-twin 10.1.278 → 10.1.279

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

@@ -1,216 +0,0 @@
-/*
- * **규칙을 주기로 돈다** — 판정을 저장소에 잇는 자리.
- *
- * ── 왜 틱이 아닌가 (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

@@ -1,84 +0,0 @@
-/*
- * 규칙 판정이 **실제 엔진·저장소에 닿는 자리** — 한 벌.
- *
- * 리졸버(「지금 돌려 본다」)와 주기 루프가 같은 배선을 써야 한다. 두 벌이면 화면에서 돌려 봤을 때와
- * 주기가 돌 때가 다르게 동작하고, 사람은 「돌려 봤을 때는 됐는데」를 겪는다.
- */
-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

@@ -1,115 +0,0 @@
-/*
- * **관측이 들어올 때 나간 지시와 잇는다** — 폐루프의 배선. 판단은 `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

@@ -1,179 +0,0 @@
-/*
- * **남은 것을 줍는 그물** — 승인은 됐는데 안 나간 것, 실패해서 다시 해 볼 것.
- *
- * ── 왜 필요한가 (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)}`))
-}