@things-factory/headless-twin 10.0.19 → 10.1.0

package/server/service/actuation/command-store.ts

@@ -5,6 +5,8 @@
  * 서지 않는다. 그러면 **게이트의 배선을 아무 시험도 걷지 않게 된다** — 훅에서 이미 겪은 부류다
  * (§`hook-store.ts`).
  */
+import { In, IsNull, Not } from 'typeorm'
+
 import { getRepository } from '@things-factory/shell'
 
 import type { TwinCommand } from '@operato/ops-contract'
@@ -12,7 +14,7 @@ import type { TwinCommand } from '@operato/ops-contract'
 import { hydratedDate } from '../../engine/read-time.js'
 
 import { TwinCommandRecord } from './twin-command.js'
-import type { CommandStore } from './command-dispatcher.js'
+import type { CommandStore, StoredCommand } from './command-dispatcher.js'
 
 /**
  * 행 → 커맨드. 상태 어휘는 계약이 정한 문자열 그대로다.
@@ -20,8 +22,12 @@ import type { CommandStore } from './command-dispatcher.js'
  * `createdAt` 은 드라이버가 준 값이라 **직접 날짜로 만들지 않는다** — 드라이버마다 모양이 다르고,
  * 문자열로 오는 드라이버에서는 시간대가 없는 값이 된다. `hydratedDate` 가 그 컬럼의 정의를 보고 푼다.
  */
-function toCommand(repo: any, row: TwinCommandRecord): TwinCommand {
+function toCommand(repo: any, row: TwinCommandRecord): StoredCommand {
   return {
+    ...(row.approvalRef ? { approvalRef: row.approvalRef } : {}),
+    ...(row.proposedBy ? { proposedBy: row.proposedBy } : {}),
+    ...(row.causeRef ? { causeRef: row.causeRef } : {}),
+    ...(row.ruleRef ? { ruleRef: row.ruleRef } : {}),
     id: row.id,
     instanceId: row.instanceId,
     type: row.type,
@@ -33,30 +39,198 @@ function toCommand(repo: any, row: TwinCommandRecord): TwinCommand {
     state: row.state as TwinCommand['state'],
     ...(row.decidedBy ? { approval: { by: row.decidedBy, at: row.decidedAt ?? '', ...(row.decisionNote ? { note: row.decisionNote } : {}) } } : {}),
     ...(row.dispatchRef ? { dispatchRef: row.dispatchRef } : {}),
+    ...(row.dispatchNote ? { dispatchNote: row.dispatchNote } : {}),
+    /* 셋이 다 있어야 효과다 — 하나라도 비면 적지 않는다(빈 값을 사실로 만들지 않는다). */
+    ...(row.effectStatus && row.effectAt
+      ? { effect: { status: row.effectStatus, at: row.effectAt, seen: row.effectSeen ?? 1 } }
+      : {}),
     ...(row.error ? { error: row.error } : {})
   }
 }
 
-/** 실제 저장소를 쓰는 구현 — 리졸버가 이것을 넣는다. */
-export function databaseCommandStore(): CommandStore {
+/**
+ * 실제 저장소를 쓰는 구현 — 리졸버가 이것을 넣는다.
+ *
+ * **트랜잭션을 받는다.** `getRepository(target)` 를 인자 없이 부르면 요청의 트랜잭션에 붙지 않고
+ * 별도로 커밋된다(`shell/initializers/database.ts:47`). 그러면 「올리고 적기」가 한 덩어리가 아니게 되고,
+ * 뒤가 실패했을 때 앞이 남는다 — 결재선에는 없는데 커맨드는 적혀 직접 결정이 열린 상태다.
+ *
+ * 콜백에서 부를 때도 넘긴다 — 업무 목록의 판정과 우리 커맨드가 같이 커밋되거나 같이 물러나야 한다.
+ */
+export function databaseCommandStore(tx?: any): CommandStore {
   return {
     load: async (domainId: string, id: string) => {
-      const repo = await getRepository(TwinCommandRecord)
+      const repo = await getRepository(TwinCommandRecord, tx)
       const row = await repo.findOne({ where: { domain: { id: domainId }, id } }).catch(() => null)
       return row ? toCommand(repo, row) : null
     },
-    save: async (domainId: string, command: TwinCommand) => {
-      await getRepository(TwinCommandRecord).update(
+
+    /**
+     * 결정을 기다리는 것들의 **근거** — 규칙이 같은 조건을 두 번 올리지 않게.
+     *
+     * 저장소에서 읽는다. 프로세스 기억에 두면 재기동이 곧 중복이 된다 — 다시 선 트윈이 같은 조건을 처음
+     * 보는 것으로 읽고 대기 줄에 같은 지시를 또 올린다.
+     *
+     * `proposed` 만 본다 — 결정을 기다리는 것은 시간과 무관하게 막는다. 결정이 끝난 것을 언제 다시 낼지는
+     * 이것이 아니라 **기다리는 시간**이 정한다(§`lastProposedAt`).
+     */
+    openCauses: async (domainId: string, instanceId: string) => {
+      const repo = await getRepository(TwinCommandRecord, tx)
+      const rows = await repo
+        .find({ where: { domain: { id: domainId }, instanceId, state: 'proposed' }, select: ['causeRef'] as any })
+        .catch(() => [] as TwinCommandRecord[])
+
+      return new Set(rows.map(r => r.causeRef).filter((v): v is string => !!v))
+    },
+
+    /**
+     * 근거마다 **마지막으로 조치를 낸 시각** — 결정이 끝난 것까지 본다.
+     *
+     * `openCauses` 만으로는 부족하다. 승인하는 순간 그 커맨드가 대기에서 빠지고 조건은 그대로 서 있어서
+     * 다음 바퀴가 같은 것을 또 낸다. 실제로 그렇게 됐다 — 승인 한 번에 대기 줄이 다시 찼다.
+     */
+    lastProposedAt: async (domainId: string, instanceId: string) => {
+      const repo = await getRepository(TwinCommandRecord, tx)
+      const rows = await repo
+        .find({ where: { domain: { id: domainId }, instanceId }, select: ['causeRef', 'createdAt'] as any })
+        .catch(() => [] as TwinCommandRecord[])
+
+      const out = new Map<string, number>()
+      for (const row of rows) {
+        if (!row.causeRef) continue
+        /* 드라이버가 준 값을 직접 날짜로 만들지 않는다 — 컬럼 정의를 보고 푼다. */
+        const at = hydratedDate(repo, 'createdAt', row.createdAt)?.getTime()
+        if (at === undefined || !Number.isFinite(at)) continue
+        const prev = out.get(row.causeRef)
+        if (prev === undefined || at > prev) out.set(row.causeRef, at)
+      }
+      return out
+    },
+
+    /**
+     * 넘긴 지시의 식별자로 찾는다 — 한 번에 묶어서 묻는다.
+     *
+     * 유입은 초당 수천 건이 지나는 자리다. 관측 하나마다 질의를 붙이면 그 경로가 느려지고, 느려지면
+     * 훅이 밀린다. 그래서 묶음 하나에 질의 하나다.
+     */
+    byDispatchRef: async (domainId: string, refs: readonly string[]) => {
+      const out = new Map<string, StoredCommand>()
+      if (!refs.length) return out
+
+      const repo = await getRepository(TwinCommandRecord, tx)
+      const rows = await repo
+        .find({ where: { domain: { id: domainId }, dispatchRef: In([...new Set(refs)]) } })
+        .catch(() => [] as TwinCommandRecord[])
+
+      for (const row of rows) {
+        if (row.dispatchRef) out.set(row.dispatchRef, toCommand(repo, row))
+      }
+      return out
+    },
+
+    /**
+     * 효과를 기다리는 조치들 — 넘긴 식별자가 있는 것만.
+     *
+     * 효과가 이미 적힌 것도 낸다. 상태는 여러 번 바뀌고(초안 → 나감 → 진행 중), 마지막 것이 남아야
+     * 화면이 「지금 저쪽에서 무엇인가」에 답할 수 있다.
+     *
+     * 결정이 안 끝난 것과 실패한 것은 빼지 않는다 — 실패로 적혔는데 저쪽은 받았을 수 있고, 그때
+     * 식별자가 있으면 그 사실이 이 길로 드러난다.
+     */
+    awaitingEffect: async (domainId: string) => {
+      const repo = await getRepository(TwinCommandRecord, tx)
+      const rows = await repo
+        .find({ where: { domain: { id: domainId }, dispatchRef: Not(IsNull()) } })
+        .catch(() => [] as TwinCommandRecord[])
+      return rows.map(row => toCommand(repo, row))
+    },
+
+    /*
+     * 넘길 차례를 기다리는 것들 — **두 상태만** 본다.
+     *
+     * `approved` 는 승인 직후 발신이 놓친 것(프로세스가 그 사이에 죽었다), `failed` 는 다시 해
+     * 볼 것이다. 그 밖의 상태는 일꾼의 일이 아니다 — `proposed` 는 승인을 기다리고 `acked` 는
+     * 종착이다.
+     *
+     * 물러섬은 여기서 걸러내지 않는다. 걸러내려면 시각 비교를 SQL 방언으로 써야 하고(이 저장소는
+     * 다섯 드라이버를 지난다), 판정은 이미 순수 함수가 한다(§`retryDecisionOf`). 대기 줄이 큰
+     * 현장이 오면 그때 인덱스와 함께 다시 본다.
+     */
+    pendingDispatch: async (domainId: string) => {
+      const repo = await getRepository(TwinCommandRecord, tx)
+      const rows = await repo
+        .find({ where: { domain: { id: domainId }, state: In(['approved', 'failed']) } })
+        .catch(() => [] as TwinCommandRecord[])
+      return rows.map(row => toCommand(repo, row))
+    },
+
+    /*
+     * 효과만 적는다 — 상태·승인·오류는 건드리지 않는다. 관측이 조치의 수명에 손을 대는 길은 두지
+     * 않는다. 그리고 도메인으로 좁힌다 — 식별자는 시스템마다 겹칠 수 있다.
+     */
+    recordEffects: async (domainId: string, updates) => {
+      const repo = await getRepository(TwinCommandRecord, tx)
+      for (const u of updates) {
+        await repo.update(
+          { id: u.commandId, domain: { id: domainId } },
+          { effectStatus: u.status, effectAt: u.at, effectSeen: u.seen } as any
+        )
+      }
+    },
+
+    /*
+     * **근거는 여기서 안 적는다.** `causeRef`·`ruleRef` 는 낼 때 정해지고 바뀌지 않는다. 이 목록에 넣으면
+     * 상태가 바뀔 때마다 다시 쓰이고, 부르는 쪽이 그 칸을 빼먹은 날 **근거가 지워진다** — 그러면 중복
+     * 판정이 그 커맨드를 못 보고 같은 지시를 또 올린다.
+     */
+    save: async (domainId: string, command: StoredCommand) => {
+      await getRepository(TwinCommandRecord, tx).update(
         { id: command.id, domain: { id: domainId } },
         {
           state: command.state,
+          approvalRef: command.approvalRef ?? null,
           decidedBy: command.approval?.by ?? null,
           decidedAt: command.approval?.at ?? null,
           decisionNote: command.approval?.note ?? null,
           dispatchRef: command.dispatchRef ?? null,
-          error: command.error ?? null
+          dispatchNote: command.dispatchNote ?? null,
+          dispatchNoteNext: command.dispatchNoteNext ?? null,
+          error: command.error ?? null,
+          /* 일꾼이 쓰는 셋 — 없으면 물러섬이 표에 안 남고 재기동마다 즉시 재시도가 된다. */
+          retry: command.retry ?? null,
+          attempts: command.attempts ?? null,
+          nextAttemptAt: command.nextAttemptAt ?? null
         } as any
       )
+    },
+
+    /*
+     * 낼 때는 커맨드가 든 것을 그대로 적는다.
+     *
+     * `proposedAt` 은 옮기지 않는다 — 그 값은 `createdAt` 에서 읽으므로(§`toCommand`), 여기서 또 적으면
+     * 같은 사실이 두 칸에 살고 하나만 고쳐지는 날이 온다. 그리고 되돌려 줄 때는 **적힌 행을 다시 읽는다**
+     * — 낸 값을 그대로 답하면 드라이버가 실제로 무엇을 적었는지 모른 채로 사람에게 보여 준다.
+     */
+    create: async (domainId: string, command: StoredCommand) => {
+      const repo = await getRepository(TwinCommandRecord, tx)
+      const saved = await repo.save({
+        id: command.id,
+        domain: { id: domainId },
+        instanceId: command.instanceId,
+        type: command.type,
+        payload: command.payload ?? null,
+        origin: command.origin,
+        proposedBy: command.proposedBy ?? null,
+        causeRef: command.causeRef ?? null,
+        ruleRef: command.ruleRef ?? null,
+        reversible: command.reversible ?? null,
+        state: command.state,
+        approvalRef: command.approvalRef ?? null
+      } as any)
+
+      const row = await repo.findOne({ where: { domain: { id: domainId }, id: saved.id } })
+      if (!row) throw new Error(`커맨드를 적었는데 다시 읽을 수 없다 (${saved.id})`)
+      return toCommand(repo, row)
     }
   }
 }

package/server/service/actuation/dispatch-after-approval.ts

@@ -0,0 +1,71 @@
+/*
+ * **승인 다음에 넘긴다** — 승인 도장과 실제 발신 사이의 한 걸음.
+ *
+ * ── 무엇이 없었나 (2026-09-04) ──────────────────────────────────────────────
+ * 사람이 결재함에서 승인하면 커맨드가 `approved` 로 앉고 **거기서 멈췄다.** 그것을 집어 현장에
+ * 보내는 것이 아무것도 없었다 — 규칙 타이머는 조치를 *내는* 일만 하고, 화면에는 넘기기 단추가
+ * 없다. 폐루프를 라이브로 확인한 것도 사람이 뮤테이션을 손으로 불러서였다.
+ *
+ * 그래서 승인은 아무 데도 닿지 않았고, 현장은 오지 않는 지시를 기다렸다. 오류는 나지 않는다.
+ *
+ * ── 왜 승인 트랜잭션 안에서 보내지 않나 ─────────────────────────────────────
+ * 승인은 업무 목록의 트랜잭션 안에서 일어난다. 그 안에서 현장에 요청을 쏘면 두 가지가 깨진다.
+ *
+ *   ① 롤백이 되돌리지 못한다. 공장에는 작업지시가 생겼는데 우리 장부는 승인을 취소한 상태가 된다.
+ *      **네트워크로 나간 것은 트랜잭션이 못 되돌린다.**
+ *   ② 트랜잭션이 원격 응답을 기다리는 동안 열려 있다. 저쪽이 느리면 결재 화면이 함께 멈춘다.
+ *
+ * 그래서 **커밋 다음으로 미룬다.** 미루면 「미룬 사이에 롤백됐으면?」이 남는데, 그것은
+ * `dispatch` 가 스스로 막는다 — 새 연결로 커맨드를 **다시 읽고** 상태를 확인한다. 롤백됐으면
+ * 승인 기록이 없어 그 자리에서 던진다(§`asApproved`). 우리가 따로 검사할 것이 없다.
+ *
+ * ── 정직한 한계 ─────────────────────────────────────────────────────────────
+ * 커밋과 발신 사이에 프로세스가 죽으면 그 커맨드는 `approved` 로 남는다. **잃지는 않지만 스스로
+ * 나가지도 않는다.** 그것을 사람이 볼 자리(「넘기지 못한 조치」 목록)와 다시 넘기는 길이 아직
+ * 없다 — 이 파일이 그 빈 자리를 메우지 않는다는 것을 여기 적어 둔다.
+ *
+ * 그리고 이 미룸은 **한 프로세스 안의 약속**이다. 여러 대로 늘리면 승인을 받은 프로세스가
+ * 보내는 것이 되고, 그 프로세스가 죽으면 위와 같다. 그때는 표를 보고 집어 가는 일꾼이 필요하다.
+ */
+import { twinWarn } from '../../engine/log.js'
+import { databaseCommandStore } from './command-store.js'
+import { dispatch } from './command-dispatcher.js'
+import { routeActuation } from '../reference/actuation-routing.js'
+
+/**
+ * 승인이 확정된 조치를 **커밋 뒤에** 현장으로 넘긴다.
+ *
+ * 부르는 쪽은 기다리지 않는다(`void`). 결재의 성공은 넘김의 성공에 달려 있지 않다 — 어댑터가
+ * 죽어 있어도 승인은 남아 있어야 하고, 그것이 승인과 넘김을 가른 이유다.
+ *
+ * **던지지 않는다.** 이 함수는 요청 밖에서 돌기 때문에, 던지면 처리되지 않은 거절이 되어
+ * 프로세스를 내린다. 넘기다 생긴 실패는 `dispatch` 가 `failed` 로 앉히고, 그 위의 예외(상태가
+ * 맞지 않음·커맨드가 사라짐)만 여기서 받아 적는다.
+ */
+export function dispatchAfterApproval(domainId: string, commandId: string): void {
+  /*
+   * `setImmediate` 로 미룬다 — 지금 열린 트랜잭션이 커밋될 기회를 준다.
+   *
+   * 이것이 커밋을 **보장하지는 않는다.** 보장은 `dispatch` 의 다시 읽기가 한다(머리말). 여기서
+   * 미루는 것은 「대개 커밋된 뒤에 읽게 하려는」 것이고, 아니면 다시 읽기가 거절한다.
+   */
+  setImmediate(() => {
+    void (async () => {
+      try {
+        const settled = await dispatch(databaseCommandStore(), domainId, commandId, command =>
+          routeActuation(domainId, command.instanceId, command)
+        )
+        if (settled.state === 'failed') {
+          /* 실패는 결함이 아니다 — 저쪽이 안 받았거나 설정이 비었다는 사실이고, 행에 남는다. */
+          twinWarn(`[twin-actuation] 조치 ${commandId} 를 넘기지 못했다: ${settled.error ?? '(사유 없음)'}`)
+        }
+      } catch (e: any) {
+        /*
+         * 여기 오는 것은 「넘길 수 없는 상태」다. 가장 흔한 원인은 **승인 트랜잭션이 롤백된 것**이고,
+         * 그때는 넘기지 않는 것이 맞다. 조용히 지나가지 않고 적는다 — 다른 원인이면 그것이 결함이다.
+         */
+        twinWarn(`[twin-actuation] 조치 ${commandId} 를 넘기지 않았다: ${String(e?.message ?? e)}`)
+      }
+    })()
+  })
+}

package/server/service/actuation/effect-match.ts

@@ -0,0 +1,124 @@
+/*
+ * **나간 지시와 돌아온 관측을 잇는다** — 폐루프의 마지막 칸. 판단만, 저장소는 여기 없다.
+ *
+ * ── 왜 이 칸이 비어 있었나 (2026-09-02) ───────────────────────────────────────
+ * `dispatchRef` 를 **쓰는 곳만 있고 읽는 곳이 없었다.** 어댑터가 답한 작업지시 이름을 적어 두는데,
+ * 그 이름으로 무엇도 찾지 않았다. 그래서 조치를 넘긴 뒤 저쪽에서 그것이 어떻게 됐는지 트윈은 몰랐다.
+ *
+ * 자리는 있고 길이 없는 상태다. 조치 경로에서 이 부류가 나면 결과가 하나다 — **넘긴 것이 현장에서
+ * 무엇이 되었는지 아무도 모르는데, 화면은 「넘겼다」까지만 보여 주고 끝난 것처럼 읽힌다.**
+ *
+ * ── 커널은 무엇이 효과인지 정하지 않는다 ─────────────────────────────────────
+ * 오더 상태 어휘는 도메인 소유다(§`OrderStatusDelta.status` — `status: string`, 코어는 강제하지
+ * 않는다). 어느 값이 「현장에 나갔다」인지는 현장마다 다르고, 커널이 그 방언을 알면 보편 계약이
+ * 깨진다 — 흐름 판정이 공정 이름을 설비 종류로 환산하지 않는 것과 같은 이유다.
+ *
+ * 그래서 여기서 판단하는 것은 **이어지나** 하나다.
+ *
+ *   이 관측의 오더 식별자가 우리가 낸 지시의 식별자와 같은가
+ *
+ * 같으면 그 상태를 **해석하지 않고 그대로** 적는다. 무엇을 뜻하는지는 그 어휘를 아는 쪽이 읽는다.
+ */
+import type { ISOTime } from '@operato/ops-contract'
+
+/** 관측 하나 — 오더 상태 보고에서 필요한 것만. */
+export interface OrderObservation {
+  orderId: string
+  status: string
+  /** 이 보고를 관측한 시각. 없으면 이을 수 없다 — 언제인지 모르는 효과는 적지 않는다. */
+  at?: ISOTime
+}
+
+/** 이을 대상 — 저장소가 `dispatchRef` 로 찾아 준 조치. */
+export interface DispatchedCommand {
+  id: string
+  dispatchRef: string
+  /** 이미 적힌 효과가 있나 — 몇 번 보고됐는지를 이어서 센다. */
+  effect?: { status: string; at: ISOTime; seen: number }
+}
+
+/** 적을 것 하나. */
+export interface EffectUpdate {
+  commandId: string
+  status: string
+  at: ISOTime
+  seen: number
+}
+
+export interface EffectMatch {
+  updates: EffectUpdate[]
+  /** 이을 수 없던 관측과 그 이유 — 조용히 버리지 않는다. */
+  skips: { orderId: string; reason: string }[]
+}
+
+/**
+ * 한 번에 여러 관측을 잇는다.
+ *
+ * **같은 오더가 한 묶음에 여러 번 올 수 있다.** 그때는 마지막 것이 남고 `seen` 이 그만큼 는다 —
+ * 중간 상태를 덮어쓰는 것이 맞다(화면이 묻는 것은 「지금 저쪽에서 무엇인가」다). 다만 몇 번 바뀌었는지는
+ * 남긴다. 한 번도 안 바뀐 것과 다섯 번 바뀐 것은 다른 일이다.
+ */
+export function matchEffects(args: {
+  observations: readonly OrderObservation[]
+  /** `dispatchRef` → 그 지시를 낸 조치. 저장소가 채운다. */
+  byRef: ReadonlyMap<string, DispatchedCommand>
+}): EffectMatch {
+  const { observations, byRef } = args
+
+  const updates = new Map<string, EffectUpdate>()
+  const skips: { orderId: string; reason: string }[] = []
+
+  for (const ob of observations) {
+    const orderId = String(ob?.orderId ?? '').trim()
+    if (!orderId) {
+      skips.push({ orderId: '', reason: '오더 식별자가 없는 보고 — 이을 수 없다' })
+      continue
+    }
+
+    const command = byRef.get(orderId)
+    if (!command) {
+      /*
+       * 대개 이것이다 — 우리가 내지 않은 오더의 상태 보고. 저쪽 시스템은 자기 오더를 다 보고하고,
+       * 그중 우리가 낸 것은 일부다. **이유로 남기되 흔한 것임을 적어 둔다** — 이 줄이 쌓이는 것을
+       * 결함으로 읽으면 안 된다.
+       */
+      skips.push({ orderId, reason: '우리가 낸 지시가 아니다' })
+      continue
+    }
+
+    const status = String(ob?.status ?? '').trim()
+    if (!status) {
+      /* 빈 상태를 적으면 「보고는 왔는데 아무 말도 안 했다」가 「효과 없음」과 같아 보인다. */
+      skips.push({ orderId, reason: '상태를 말하지 않은 보고 — 빈 값을 효과로 적지 않는다' })
+      continue
+    }
+
+    const at = String(ob?.at ?? '').trim()
+    if (!at) {
+      /* 언제인지 모르는 효과는 적지 않는다 — 「지금」으로 채우면 관측 시각이 아니라 처리 시각이 된다. */
+      skips.push({ orderId, reason: '시각이 없는 보고 — 지금으로 채우지 않는다' })
+      continue
+    }
+
+    /* 같은 묶음 안에서 앞서 센 것이 있으면 그것을 잇는다 — 없으면 적힌 효과에서 잇는다. */
+    const prior = updates.get(command.id)?.seen ?? command.effect?.seen ?? 0
+    updates.set(command.id, { commandId: command.id, status, at, seen: prior + 1 })
+  }
+
+  return { updates: [...updates.values()], skips }
+}
+
+/**
+ * 이 묶음에서 **찾아봐야 할 오더 식별자**만 골라낸다 — 저장소에 물을 것을 줄인다.
+ *
+ * 관측 한 묶음이 수백 건일 수 있고 그중 우리가 낸 것은 몇 건이다. 전부를 하나씩 물으면 유입 경로에
+ * 질의가 그만큼 붙는다 — 유입은 초당 수천 건이 지나는 자리다.
+ */
+export function refsToLookUp(observations: readonly OrderObservation[]): string[] {
+  const out = new Set<string>()
+  for (const ob of observations) {
+    const orderId = String(ob?.orderId ?? '').trim()
+    if (orderId) out.add(orderId)
+  }
+  return [...out]
+}

package/server/service/actuation/index.ts

@@ -1,8 +1,27 @@
+import { TwinActuationRule } from './actuation-rule.js'
+import { TwinActuationRuleResolver } from './actuation-rule-resolver.js'
 import { TwinCommandRecord } from './twin-command.js'
+import { TwinCommandResolver } from './twin-command-resolver.js'
 
-export const entities = [TwinCommandRecord]
-export const resolvers = []
+export const entities = [TwinCommandRecord, TwinActuationRule]
+export const resolvers = [TwinCommandResolver, TwinActuationRuleResolver]
 
 export * from './twin-command.js'
+export * from './actuation-rule.js'
+export * from './approval-gateway.js'
+export * from './dispatch-after-approval.js'
+export * from './actuation-outcome.js'
+export * from './retry-plan.js'
+export * from './sweep-dispatch.js'
+export * from './actuation-advisor.js'
 export * from './command-dispatcher.js'
 export * from './command-store.js'
+export * from './twin-now.js'
+export * from './effect-match.js'
+export * from './settle-effects.js'
+export * from './catch-up-effects.js'
+export * from './rule-evaluate.js'
+export * from './rule-runner.js'
+export * from './rule-loop.js'
+export * from './twin-command-resolver.js'
+export * from './actuation-rule-resolver.js'

package/server/service/actuation/retry-plan.ts

@@ -0,0 +1,145 @@
+/*
+ * **다시 넘길 것인가, 언제인가** — 일꾼이 묻는 것 하나.
+ *
+ * ── 왜 순수한가 ─────────────────────────────────────────────────────────────
+ * 일꾼의 판단이 전부 여기 있다. DB 도 어댑터도 시계도 보지 않는다 — 시각은 받는다. 그래서 「10분
+ * 뒤에 다시」 같은 규칙을 기다리지 않고 값만 바꿔 가며 잴 수 있다.
+ *
+ * ── 세 갈래는 어댑터가 답한다 ───────────────────────────────────────────────
+ * 실패가 다 같지 않다. 2026-09-02 에 둘을 겪었다 — 저쪽 인증 정보가 없어 503(고치면 됨)이었고,
+ * `ITEM-1` 은 400(고쳐도 이 조치로는 안 됨)이었다. 답만 보면 구별되지 않았다.
+ *
+ *   again       그대로 다시 해 볼 만하다      못 닿았거나 저쪽이 잠깐 흔들렸다
+ *   after-fix   사람이 고친 뒤 그대로 나간다   설정 문제
+ *   never       이 조치로는 영원히 안 된다     지시 내용이 틀렸다
+ *
+ * 가르는 자리는 **「조치를 다시 낼 필요가 있나」**다(인티그레이션 레인 판단).
+ *
+ * ── `after-fix` 를 횟수로 접지 않는다 ───────────────────────────────────────
+ * 이것이 이 파일에서 가장 중요한 결정이다. `after-fix` 는 **재시도가 아니라 기다리는 것**이다.
+ * 두드려서 풀릴 일이 아니고, 사람이 설정을 고치는 순간 다음 주기에 나가면 된다.
+ *
+ * 횟수로 접으면 **사람이 고쳐 놓고도 다시 손으로 눌러야** 한다. 2026-09-02 사고가 정확히 그
+ * 모양이었다 — 저쪽이 고쳐진 뒤 사람이 손으로 다시 넘겨서 나갔다.
+ *
+ * `again` 만 접는다. 끝없이 두드리는 것은 소음이고, 짧게 세 번 해서 안 되면 망이 흔들린 것이
+ * 아니라 다른 것이다 — 그때는 사람이 봐야 한다.
+ *
+ * ── 멱등이 첫 시도와 재시도를 가른다 ────────────────────────────────────────
+ *   approved → 넘김    **첫 시도**다. 멱등 선언이 없어도 한다 — 한 번뿐이라 위험이 없다
+ *   failed → 넘김      **재시도**다. 두 번 보내도 지시가 하나라고 선언한 커넥터만 한다
+ *
+ * 선언하지 않은 커넥터의 실패는 목록에 남는다. 사람이 저쪽 상태를 보고 결정해야 한다 — 우리가
+ * 「아마 괜찮겠지」로 두 번 보내면 현장에 지시가 두 건 선다.
+ */
+
+/** 어댑터가 답하는 세 갈래. 비어 있으면 **말하지 않은 것**이고, `never` 가 아니다. */
+export type RetryOutlook = 'again' | 'after-fix' | 'never'
+
+export function isRetryOutlook(v: unknown): v is RetryOutlook {
+  return v === 'again' || v === 'after-fix' || v === 'never'
+}
+
+/**
+ * `again` 의 물러섬 — 30초 · 2분 · 10분, 그다음 접는다.
+ *
+ * 첫 값이 일꾼의 주기와 같다(§`RULE_PERIOD_MS`). 새 박자를 만들지 않는다.
+ */
+export const AGAIN_BACKOFF_MS = [30_000, 120_000, 600_000] as const
+
+/**
+ * `after-fix` 는 **10분마다 계속** 본다 — 접지 않는다(머리말).
+ *
+ * 사람이 설정을 고치는 것을 기다리는 간격이다. 짧게 두면 헛되고, 길게 두면 고쳐 놓고 기다린다.
+ */
+export const AFTER_FIX_PERIOD_MS = 600_000
+
+/** 왜 집지 않는가 — 목록이 「고칠 것」과 「우리 쪽을 보지 말 것」을 갈라 보이게 한다. */
+export type SkipReason =
+  /** 종착이거나 넘길 수 없는 상태다. */
+  | 'not-dispatchable'
+  /** 아직 물러섬이 끝나지 않았다 — 다음 기회를 기다린다. */
+  | 'backing-off'
+  /** 어댑터가 「영원히 안 된다」고 답했다 — 사람이 **새 조치**를 내야 한다. 우리 쪽에 고칠 것이 없다. */
+  | 'never'
+  /** `again` 을 세 번 다 썼다 — 사람이 봐야 한다. */
+  | 'attempts-spent'
+  /** 어댑터가 다시 될 일인지 말하지 않았다 — 모르는 것을 재시도로 밀지 않는다. */
+  | 'outlook-unknown'
+  /** 재시도인데 커넥터가 멱등을 선언하지 않았다 — 두 건이 설 위험을 우리가 지지 않는다. */
+  | 'not-idempotent'
+
+export interface RetryDecision {
+  /** 지금 넘길 것인가. */
+  take: boolean
+  /** 안 넘기면 왜 — 목록이 그대로 보인다. */
+  skip?: SkipReason
+  /** 넘길 것이면 이번이 몇 번째 시도인가(첫 시도가 1). */
+  attempt?: number
+  /** 이번 시도가 실패하면 다음은 언제인가(ISO). 없으면 더 안 본다. */
+  nextAttemptAt?: string
+}
+
+export interface RetryInput {
+  /** 지금 상태 — `approved` 는 첫 시도, `failed` 는 재시도. */
+  state: string
+  /** 넘길 수 있는 상태인가 — 상태 기계가 답한다(`nextCommandState(state,'dispatch')`). */
+  dispatchable: boolean
+  /** 어댑터가 지난 실패에 답한 갈래. 첫 시도에는 없다. */
+  retry?: string
+  /** 지금까지 몇 번 넘겨 봤나. 없으면 0. */
+  attempts?: number
+  /** 다음에 볼 시각(ISO). 없으면 지금 봐도 된다. */
+  nextAttemptAt?: string
+  /** 이 커넥터가 두 번 보내도 지시가 하나인가 — **선언만 참으로 읽는다.** */
+  idempotent?: boolean
+  /** 지금(ms). */
+  nowMs: number
+}
+
+const at = (ms: number): string => new Date(ms).toISOString()
+
+/**
+ * 이 조치를 지금 넘길 것인가.
+ *
+ * **모르면 넘기지 않는다.** 어댑터가 갈래를 말하지 않았거나 멱등을 선언하지 않았으면 재시도하지
+ * 않고 목록에 남긴다 — 오늘 커널의 다른 축에서 지킨 것과 같은 규율이다(정격 사용량·품질 계수기·
+ * 조용한 시각: 모르면 단언하지 않는다).
+ */
+export function retryDecisionOf(input: RetryInput): RetryDecision {
+  if (!input.dispatchable) return { take: false, skip: 'not-dispatchable' }
+
+  const attempts = typeof input.attempts === 'number' && input.attempts > 0 ? input.attempts : 0
+
+  /*
+   * **첫 시도** — 승인됐는데 한 번도 안 나간 것. 물러섬도 멱등도 묻지 않는다: 한 번뿐이라 두 건이
+   * 설 수 없고, 어댑터는 아직 아무 답도 하지 않았다.
+   *
+   * 이 갈래가 승인 직후 발신이 놓친 것을 줍는다 — 커밋과 발신 사이에 프로세스가 죽은 경우다.
+   */
+  if (attempts === 0) {
+    return { take: true, attempt: 1, nextAttemptAt: at(input.nowMs + AGAIN_BACKOFF_MS[0]) }
+  }
+
+  /* 재시도다. 여기서부터 어댑터의 답과 커넥터의 성질을 묻는다. */
+  if (!isRetryOutlook(input.retry)) return { take: false, skip: 'outlook-unknown' }
+  if (input.retry === 'never') return { take: false, skip: 'never' }
+  if (input.idempotent !== true) return { take: false, skip: 'not-idempotent' }
+
+  if (input.nextAttemptAt) {
+    const dueMs = Date.parse(input.nextAttemptAt)
+    /* 읽을 수 없는 값으로 막지 않는다 — 막으면 그 조치가 표에 갇힌다. */
+    if (Number.isFinite(dueMs) && input.nowMs < dueMs) return { take: false, skip: 'backing-off' }
+  }
+
+  if (input.retry === 'after-fix') {
+    /* 접지 않는다(머리말) — 같은 간격으로 계속 본다. */
+    return { take: true, attempt: attempts + 1, nextAttemptAt: at(input.nowMs + AFTER_FIX_PERIOD_MS) }
+  }
+
+  /* `again` — 물러섬 표를 다 쓰면 접는다. */
+  if (attempts >= AGAIN_BACKOFF_MS.length) return { take: false, skip: 'attempts-spent' }
+
+  const next = AGAIN_BACKOFF_MS[attempts]
+  return { take: true, attempt: attempts + 1, nextAttemptAt: at(input.nowMs + next) }
+}