@things-factory/headless-twin 10.1.278 → 10.1.280

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

@@ -1,236 +0,0 @@
-/*
- * 커맨드가 저장소에 닿는 두 자리 — 찾는 것과 적는 것.
- *
- * 디스패처가 엔티티를 직접 가져오면 그 파일을 부르는 시험이 TypeORM 데코레이터를 지나게 되고, 시험이
- * 서지 않는다. 그러면 **게이트의 배선을 아무 시험도 걷지 않게 된다** — 훅에서 이미 겪은 부류다
- * (§`hook-store.ts`).
- */
-import { In, IsNull, Not } from 'typeorm'
-
-import { getRepository } from '@things-factory/shell'
-
-import type { TwinCommand } from '@operato/ops-contract'
-
-import { hydratedDate } from '../../engine/read-time.js'
-
-import { TwinCommandRecord } from './twin-command.js'
-import type { CommandStore, StoredCommand } from './command-dispatcher.js'
-
-/**
- * 행 → 커맨드. 상태 어휘는 계약이 정한 문자열 그대로다.
- *
- * `createdAt` 은 드라이버가 준 값이라 **직접 날짜로 만들지 않는다** — 드라이버마다 모양이 다르고,
- * 문자열로 오는 드라이버에서는 시간대가 없는 값이 된다. `hydratedDate` 가 그 컬럼의 정의를 보고 푼다.
- */
-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,
-    ...(row.payload ? { payload: row.payload } : {}),
-    origin: row.origin as TwinCommand['origin'],
-    proposedAt: hydratedDate(repo, 'createdAt', row.createdAt)?.toISOString() ?? '',
-    /* 없는 것을 거짓으로 채우지 않는다 — 비어 있음이 「되돌릴 수 없다」의 뜻이다. */
-    ...(row.reversible === null || row.reversible === undefined ? {} : { reversible: row.reversible }),
-    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 } : {})
-  }
-}
-
-/**
- * 실제 저장소를 쓰는 구현 — 리졸버가 이것을 넣는다.
- *
- * **트랜잭션을 받는다.** `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, tx)
-      const row = await repo.findOne({ where: { domain: { id: domainId }, id } }).catch(() => null)
-      return row ? toCommand(repo, row) : null
-    },
-
-    /**
-     * 결정을 기다리는 것들의 **근거** — 규칙이 같은 조건을 두 번 올리지 않게.
-     *
-     * 저장소에서 읽는다. 프로세스 기억에 두면 재기동이 곧 중복이 된다 — 다시 선 트윈이 같은 조건을 처음
-     * 보는 것으로 읽고 대기 줄에 같은 지시를 또 올린다.
-     *
-     * `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,
-          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

@@ -1,71 +0,0 @@
-/*
- * **승인 다음에 넘긴다** — 승인 도장과 실제 발신 사이의 한 걸음.
- *
- * ── 무엇이 없었나 (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

@@ -1,124 +0,0 @@
-/*
- * **나간 지시와 돌아온 관측을 잇는다** — 폐루프의 마지막 칸. 판단만, 저장소는 여기 없다.
- *
- * ── 왜 이 칸이 비어 있었나 (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,27 +0,0 @@
-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, 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

@@ -1,145 +0,0 @@
-/*
- * **다시 넘길 것인가, 언제인가** — 일꾼이 묻는 것 하나.
- *
- * ── 왜 순수한가 ─────────────────────────────────────────────────────────────
- * 일꾼의 판단이 전부 여기 있다. 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) }
-}