@things-factory/headless-twin 10.0.19 → 10.1.0

package/server/service/actuation/actuation-advisor.ts

@@ -0,0 +1,124 @@
+/*
+ * **AI 가 의견을 내는 자리** — 판정이 아니라 발언.
+ *
+ * ── 왜 필요한가 (2026-09-01, 사용자 지적) ────────────────────────────────
+ * 사용자가 물었다 — 「AI 자신은 결재/승인의 담당이 될 수 없나. 최소한 의견제시자라도 될 수 있지 않나.」
+ *
+ * 승인자는 안 된다. 승인 기록의 값어치는 사고 뒤에 **책임을 물을 수 있는 것**이고, 「AI 가 승인했다」로는
+ * 아무에게도 묻지 못한다. 그리고 낸 쪽이 승인하면 두 사람이 아니다 — 자기 승인을 막는 규칙과 같은 이유다.
+ *
+ * 의견은 내야 한다. `twinNow` 로 「도금 대기가 여섯 배다」는 사실을 승인 화면에 실었지만, 그건 계산값이다.
+ * 「그러니 더 만들면 대기가 늘어난다」가 의견이고 그 자리가 없었다.
+ *
+ * ── 언제 묻나 — 승인 화면을 열 때다 ─────────────────────────────────────
+ * 결재선에 올릴 때 묻지 않는다. 그 자리는 트랜잭션 안이고(`raiseTwinCommand` 의 `@transaction`),
+ * 거기서 LLM 을 기다리면 **DB 연결 하나를 몇 초 붙잡는다**(sqlite 는 연결이 하나다).
+ *
+ * 그리고 화면을 열 때 묻는 것이 더 옳다. 승인하는 사람은 **지금** 판단하고, 올린 시각의 의견은 낡았다.
+ *
+ * ── 판정에 쓰지 않는다 ───────────────────────────────────────────────────
+ * 이 값을 읽어 무엇을 막는 코드가 없다. 승인·거절은 사람이 한다. AI 가 반대해도 승인되고, 동의해도
+ * 거절된다. 그 사실이 코드에 드러나 있어야 한다 — 판정에 쓰면 AI 가 사실상 승인자가 된다.
+ */
+import type { StoredCommand } from './command-dispatcher.js'
+import type { TwinNow } from './twin-now.js'
+
+/**
+ * AI 가 어떤 태도를 냈나 — **세 갈래여야 한다.**
+ *
+ * 「모르겠다」가 없으면 모를 때 동의로 답한다. 그리고 승인자가 그것을 「AI 가 괜찮다고 했다」로 읽는다.
+ * 자동 승인 편향이 거기서 시작한다.
+ */
+export type AdvisorStance = 'object' | 'concur' | 'unsure'
+
+export interface AdvisorOpinion {
+  stance: AdvisorStance
+  /** 사람이 읽는 문장. AI 가 쓴 그대로 — 우리가 다듬지 않는다(다듬으면 누가 말한 것인지 흐려진다). */
+  text: string
+  /** 무엇을 보고 말했나 — 주의 식별자·값. 승인자가 근거를 되짚을 수 있게. */
+  basis?: string[]
+}
+
+/** 의견을 내는 자리 — 앱이 채운다(headless-twin 은 `twin-ai` 를 부르지 않는다). */
+export interface ActuationAdvisor {
+  /** 화면이 출처를 말해야 한다 — 「AI 의견」. 사람의 의견과 섞이면 안 된다. */
+  label: string
+  /**
+   * 이 조치에 대해 한마디.
+   *
+   * 실패·시간초과면 `undefined` 를 돌려준다. 지어내지 않는다.
+   */
+  advise(input: {
+    command: StoredCommand
+    twinNow: TwinNow
+    locale?: string
+  }): Promise<AdvisorOpinion | undefined>
+}
+
+let advisor: ActuationAdvisor | undefined
+
+/** 앱이 부팅에서 한 번 부른다. */
+export function setActuationAdvisor(next: ActuationAdvisor): void {
+  advisor = next
+}
+
+export function actuationAdvisor(): ActuationAdvisor | undefined {
+  return advisor
+}
+
+/** 의견을 물은 결과 — **없음도 사실이다.** */
+export interface AdvisorResult {
+  /** 누가 말했나. 없으면 아무도 말하지 않았다. */
+  by?: string
+  opinion?: AdvisorOpinion
+  /**
+   * 의견이 없으면 왜 없나.
+   *
+   * 빈칸을 「AI 가 반대하지 않았다」로 읽으면 안 된다. 화면이 이 문장을 그대로 보여야 한다.
+   */
+  absent?: string
+}
+
+/** 몇 초까지 기다리나 — 승인 화면이 이것 때문에 안 열리면 안 된다. */
+export const ADVISOR_BUDGET_MS = 8_000
+
+/**
+ * 의견을 묻는다 — **없으면 없다고 답한다.**
+ *
+ * 실패를 삼키지 않는다. AI 가 죽어 있어서 의견이 없는 것과 AI 가 반대할 것이 없어서 조용한 것은 다른
+ * 사실이고, 승인하는 사람에게 그 차이가 크다.
+ */
+export async function askAdvisor(args: {
+  command: StoredCommand
+  twinNow: TwinNow
+  locale?: string
+  budgetMs?: number
+}): Promise<AdvisorResult> {
+  const a = advisor
+  if (!a) return { absent: 'AI 의견을 내는 자리가 설치되지 않았습니다' }
+
+  const budget = args.budgetMs ?? ADVISOR_BUDGET_MS
+  let timer: any
+  try {
+    const opinion = await Promise.race([
+      a.advise({ command: args.command, twinNow: args.twinNow, ...(args.locale ? { locale: args.locale } : {}) }),
+      new Promise<undefined>(resolve => {
+        timer = setTimeout(() => resolve(TIMED_OUT as any), budget)
+      })
+    ])
+
+    if ((opinion as any) === TIMED_OUT) {
+      return { by: a.label, absent: `${Math.round(budget / 1000)}초 안에 답이 오지 않았습니다` }
+    }
+    if (!opinion?.text?.trim()) return { by: a.label, absent: 'AI 가 할 말이 없다고 답했습니다' }
+
+    return { by: a.label, opinion }
+  } catch (e: any) {
+    return { by: a.label, absent: `의견을 받지 못했습니다 — ${String(e?.message ?? e)}` }
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+/** 시간초과를 값으로 구별한다 — `undefined` 로 두면 「할 말 없음」과 섞인다. */
+const TIMED_OUT = Symbol('advisor-timeout')

package/server/service/actuation/actuation-outcome.ts

@@ -0,0 +1,97 @@
+/*
+ * **조치가 어떻게 됐나** — 승인한 사람에게 돌려줄 사실 한 묶음.
+ *
+ * ── 왜 판정을 커널이 하나 (2026-09-04) ─────────────────────────────────────
+ * 「저쪽에서 사람이 할 일이 남았나」의 답이 한 필드에 없다. `dispatchNote` 만 보면 틀린다 —
+ * 그 문장은 **넘길 때 저쪽이 한 말**이고, 사람이 나중에 지시서를 골라도 그대로 남는다. 저쪽에
+ * 다시 물을 일이 없으니 갱신되지 않는다(인티그레이션 레인이 MES 코드를 읽어 찾았다: 다시 보내면
+ * 지금 상태를 답하는데, `acked` 가 종착이라 다시 보낼 일이 없다).
+ *
+ * 그러니 답은 **「그 문장이 있고 효과가 아직 없을 때」**다. 그 겹침을 화면마다 하게 두면 목록·
+ * 상세·알림이 각자 겹치고, 한 곳이 빠진 날 그 화면만 다른 말을 한다. 오늘 설비 등급 소속에서
+ * 같은 이유로 합침을 계약 한 자리에 뒀다.
+ *
+ * ── 커널은 저쪽 말을 해석하지 않는다 ───────────────────────────────────────
+ * `effectStatus` 는 원천이 보낸 낱말 그대로다(§`QualityDelta` 와 같은 규율). 여기서 보는 것은
+ * **그 값이 있는가**뿐이고, `released` 인지 `closed` 인지는 도메인의 뜻이라 커널이 가르지 않는다.
+ */
+import type { StoredCommand } from './command-dispatcher.js'
+
+/** 승인한 사람에게 돌려줄 것 — 화면이 겹쳐 볼 것이 없게 판정까지 낸다. */
+export interface ActuationOutcome {
+  id: string
+  /** proposed · approved · dispatching · acked · failed · rejected. */
+  state: string
+  /** 저쪽이 준 이름 — 나갔을 때만. 없으면 무엇을 되돌릴지 지목할 수 없다. */
+  dispatchRef?: string
+  /** 못 나간 사유 — 저쪽 문장 그대로. */
+  error?: string
+  /** 저쪽이 받으면서 덧붙인 말 — **실패가 아니다.** 원인 쪽 문장. */
+  note?: string
+  /**
+   * 그 말 중 **다음에 할 일** 한 줄.
+   *
+   * 왜 둘로 오나: 읽는 사람은 「그래서 내가 뭘 해야 하나」를 먼저 찾는다(UX 레인). 한 문장으로
+   * 주면 화면이 자르게 되고, **자르는 규칙이 화면마다 생긴다.** 어댑터가 이미 둘로 알고 있으니
+   * 붙이지 않고 그대로 나른다.
+   *
+   * 어댑터가 아직 갈라 주지 않으면 **비어 있다.** 그때 `note` 는 두 문장이 붙은 한 덩이이고,
+   * 화면은 그것을 통째로 그려야 한다 — 파싱해서 나누면 어댑터가 갈라 주는 날 조용히 깨진다.
+   */
+  noteNext?: string
+  /** 원천이 보고한 상태 — 낱말 그대로. */
+  effectStatus?: string
+  /** 그 보고를 본 시각. */
+  effectAt?: string
+  /**
+   * 되돌릴 수 있나 — 화면은 **참일 때만** 한 줄 낸다.
+   *
+   * 지금 규칙에서 결재함에 올라온 조치는 거의 다 되돌릴 수 없다(되돌릴 수 없는 것만 승인을
+   * 요구한다). 그래서 「되돌릴 수 없습니다」를 매번 적으면 늘 참인 경고가 되고, 늘 참인 경고는
+   * 사흘이면 안 읽힌다 — 그러면 그 자리에 다른 말이 필요한 날 자리가 이미 죽어 있다(UX 레인 판단).
+   */
+  reversible?: boolean
+  /**
+   * **저쪽에서 사람이 할 일이 남았나** — 이 판정이 이 타입의 존재 이유다(머리말).
+   *
+   * 「모른다」가 있다: 아직 넘기지 않았으면 물어볼 것이 없다. `false` 로 접으면 화면이 「할 일
+   * 없음」으로 그리고, 그것은 넘긴 뒤와 구별되지 않는다.
+   */
+  pendingAtSource?: boolean
+  /** 넘길 수 있는 상태인가 — `acked` 는 종착이라 저쪽이 준비돼 있어도 다시 넘기지 않는다. */
+  dispatchable: boolean
+}
+
+/** 넘김을 시도해 본 상태인가 — 이 뒤에야 「저쪽에 할 일이 남았나」를 물을 수 있다. */
+const TRIED = new Set(['dispatching', 'acked', 'failed'])
+
+/**
+ * 저장된 조치 하나를 사람이 읽을 사실로 옮긴다 — **순수하다.**
+ *
+ * DB 도 어댑터도 보지 않는다. 그래서 이 판정은 시험이 값만 바꿔 가며 확인할 수 있고, 화면이
+ * 같은 규칙을 다시 쓰지 않아도 된다.
+ */
+export function actuationOutcomeOf(command: StoredCommand, dispatchable: boolean): ActuationOutcome {
+  const note = command.dispatchNote
+  const effect = command.effect
+
+  /*
+   * 넘겨 보지 않았으면 판정하지 않는다. 넘긴 뒤라면 「말이 있는데 효과가 아직 없다」가 곧
+   * 「저쪽에서 사람이 할 일이 남았다」다.
+   */
+  const pendingAtSource = TRIED.has(command.state) ? Boolean(note) && !effect?.status : undefined
+
+  return {
+    id: command.id,
+    state: command.state,
+    ...(command.dispatchRef ? { dispatchRef: command.dispatchRef } : {}),
+    ...(command.error ? { error: command.error } : {}),
+    ...(note ? { note } : {}),
+    ...(command.dispatchNoteNext ? { noteNext: command.dispatchNoteNext } : {}),
+    ...(effect?.status ? { effectStatus: effect.status } : {}),
+    ...(effect?.at ? { effectAt: effect.at } : {}),
+    ...(command.reversible === undefined ? {} : { reversible: command.reversible }),
+    ...(pendingAtSource === undefined ? {} : { pendingAtSource }),
+    dispatchable
+  }
+}

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

@@ -0,0 +1,147 @@
+/*
+ * 규칙을 만들고 끄는 자리, 그리고 **지금 한 번 돌려 보는 자리**.
+ *
+ * ── 왜 「지금 돌린다」가 있나 ────────────────────────────────────────────
+ * 규칙을 만든 사람이 가장 먼저 묻는 것은 「이게 걸리나」다. 주기를 기다려 보라고 하면 그 사이에 무엇이
+ * 잘못됐는지 알 수 없고, 조건이 그때까지 살아 있을지도 모른다. 돌려 보면 **무엇을 냈고 무엇을 왜 안
+ * 냈는지**가 그 자리에서 답으로 온다.
+ */
+import { Arg, Args, Ctx, Directive, Mutation, Query, Resolver } from 'type-graphql'
+
+import { CMD, MES_COMMANDS } from '@operato/ops-contract'
+
+import { ListParam, ScalarObject, getQueryBuilderFromListParams, getRepository } from '@things-factory/shell'
+
+import { TwinEngine } from '../../engine/twin-engine.js'
+
+import { TwinActuationRule } from './actuation-rule.js'
+import { commandTypeGap } from './rule-evaluate.js'
+import { runRulesOnce } from './rule-runner.js'
+import { databaseCommandStore } from './command-store.js'
+import { rulesOf, noteRun, attentionsOf, modeOf } from './rule-wiring.js'
+
+@Resolver()
+export class TwinActuationRuleResolver {
+  @Query(returns => ScalarObject, {
+    nullable: true,
+    description: 'List actuation rules with the standard list contract.'
+  })
+  async twinActuationRules(
+    @Args(type => ListParam) params: ListParam,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    const domain = context.state.domain
+    if (!domain?.id) return { items: [], total: 0 }
+
+    const qb = getQueryBuilderFromListParams({
+      repository: getRepository(TwinActuationRule),
+      params,
+      domain,
+      alias: 'r',
+      searchables: ['instanceId', 'name', 'attentionKind', 'commandType', 'lastSkipReason'],
+      sortables: ['createdAt', 'updatedAt', 'instanceId', 'attentionKind', 'commandType', 'lastRunAt'],
+      defaultLimit: 50,
+      maxLimit: 200
+    })
+
+    const [items, total] = await qb.getManyAndCount()
+    return { items, total }
+  }
+
+  /**
+   * 규칙을 세우거나 고친다.
+   *
+   * **낼 수 없는 종류는 저장하지 않는다.** 저장은 되는데 안 도는 규칙이 생기면 사람은 규칙이 걸린 줄로
+   * 읽는다. 판정과 같은 검사를 지난다(§`commandTypeGap`) — 두 벌이면 어긋난다.
+   */
+  @Directive('@transaction')
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, { description: 'Create or update one actuation rule.' })
+  async saveTwinActuationRule(
+    @Arg('patch', type => ScalarObject) patch: any,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    const { domain, user, tx } = context.state
+
+    const instanceId = String(patch?.instanceId ?? '').trim()
+    if (!instanceId) throw new Error('어느 트윈의 규칙인지 말해야 합니다 — 전역 규칙은 두지 않습니다')
+
+    const attentionKind = String(patch?.attentionKind ?? '').trim()
+    if (!attentionKind) throw new Error('어느 관측에 걸 것인지 말해야 합니다')
+
+    const commandType = String(patch?.commandType ?? '').trim()
+    const gap = commandTypeGap(commandType, MES_COMMANDS, Object.values(CMD) as string[])
+    if (gap) throw new Error(gap)
+
+    const repo = getRepository(TwinActuationRule, tx)
+    const saved = await repo.save({
+      ...(patch.id ? { id: patch.id } : {}),
+      domain,
+      instanceId,
+      name: patch.name ?? null,
+      attentionKind,
+      minSeverity: patch.minSeverity ?? null,
+      minHeldMs: patch.minHeldMs ?? null,
+      /* 비워 두면 기본값(한 시간)이 걸린다. 0 은 「기다리지 않는다」는 뜻이라 그대로 존중한다. */
+      cooldownMs: patch.cooldownMs ?? null,
+      commandType,
+      payloadTemplate: patch.payloadTemplate ?? null,
+      /* 비어 있음을 「끔」으로 읽지 않는다 — 새로 만든 규칙은 켜져 있는 것이 사람의 뜻이다. */
+      enabled: patch.enabled === false ? false : true,
+      ...(patch.id ? {} : { creator: user }),
+      updater: user
+    } as any)
+
+    return saved
+  }
+
+  @Directive('@transaction')
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, { description: 'Delete one actuation rule.' })
+  async deleteTwinActuationRule(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<any> {
+    const { domain, tx } = context.state
+    const result = await getRepository(TwinActuationRule, tx).delete({ id, domain: { id: domain.id } } as any)
+    if (!result.affected) throw new Error(`모르는 규칙입니다 (${id})`)
+    return { deleted: id }
+  }
+
+  /**
+   * **지금 한 번 돌린다** — 무엇을 냈고 무엇을 왜 안 냈는지 그대로 답한다.
+   *
+   * 낸 조치는 제안 상태로 남는다. 결재선에 올리는 것은 사람이 따로 한다(§`raiseTwinCommand`) — 규칙이
+   * 올리지 않는 이유가 여기에도 그대로 적용된다(결재선은 올린 사람 기준으로 풀린다).
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, { description: 'Evaluate actuation rules once now and report what happened.' })
+  async runTwinActuationRules(
+    @Arg('instanceId', { nullable: true }) instanceId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    const domainId = context.state.domain?.id
+    if (!domainId) throw new Error('테넌트를 알 수 없습니다')
+
+    /*
+     * 트랜잭션을 넘기지 않는다 — 이 자리는 여러 트윈을 돌고, 한 트윈이 실패해도 앞의 트윈이 낸 것은
+     * 남아야 한다. 한 덩어리로 묶으면 마지막 트윈의 실패가 앞의 결과를 전부 물린다.
+     */
+    const store = databaseCommandStore()
+
+    const owned = TwinEngine.ownedTwins(domainId).filter(t => !instanceId || t.instanceId === instanceId)
+    if (instanceId && !owned.length) {
+      throw new Error(`이 서버가 들고 있지 않은 트윈입니다 (${instanceId}) — 멈춰 있거나 다른 서버가 돌고 있습니다`)
+    }
+
+    const reports = await runRulesOnce({
+      ownedTwins: () => owned,
+      rulesOf: twin => rulesOf(twin),
+      attentionsOf,
+      modeOf,
+      store,
+      specs: MES_COMMANDS,
+      nowMs: () => Date.now(),
+      noteRun
+    })
+
+    return { reports, proposed: reports.reduce((n, r) => n + r.proposed, 0) }
+  }
+}

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

@@ -0,0 +1,139 @@
+/*
+ * **어느 관측에 어느 지시를 붙이는가** — 선언 한 행.
+ *
+ * ── 왜 표인가 (2026-09-01) ───────────────────────────────────────────────
+ * 규칙은 현장이 정한다. 「병목이 세 시간 넘으면 추가 생산을 올린다」는 그 공장의 정책이고, 코드에 박으면
+ * 공장마다 포크가 생긴다. 그리고 **끌 수 있어야 한다** — 규칙이 잘못 낸 것을 본 사람이 가장 먼저 하려는
+ * 일이 그것이다.
+ *
+ * ── 판정은 여기 없다 ─────────────────────────────────────────────────────
+ * 무엇을 올릴지는 `rule-evaluate.ts` 가 든다. 이 파일은 값을 담기만 한다 — 판정이 두 벌이 되면 화면과
+ * 서버가 다른 답을 낸다.
+ *
+ * ── 계약에 넣지 않았다 ───────────────────────────────────────────────────
+ * 이 규칙이 가리키는 두 값(`Attention.kind` · `CommandTypeSpec.type`)은 계약의 어휘다. 그러나 「그 둘을
+ * 어떻게 잇는가」는 이 호스트의 배선이다 — 커널은 규칙을 읽지 않고, 커널을 쓰는 다른 소비처가 이 표를
+ * 알 이유가 없다.
+ */
+import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId, UpdateDateColumn } from 'typeorm'
+import { Field, ID, ObjectType } from 'type-graphql'
+
+import { Domain, ScalarObject } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+
+@Entity()
+/* 판정이 이 두 칸으로 묻는다 — 이 테넌트의 · 이 트윈의 규칙. */
+@Index('ix_twin_actuation_rule_0', (e: TwinActuationRule) => [e.domain, e.instanceId])
+@ObjectType({ description: 'One rule mapping an observed condition to a field instruction that needs approval.' })
+export class TwinActuationRule {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the rule.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Tenant this rule belongs to.' })
+  domain?: Domain
+
+  @RelationId((e: TwinActuationRule) => e.domain)
+  domainId?: string
+
+  /**
+   * **어느 트윈인가** — 전역 규칙을 두지 않는다.
+   *
+   * 라인이 공장마다 다르므로 한 규칙이 모든 트윈에 걸리면 어느 공장에서는 반드시 틀린다. 트윈을 지목하면
+   * 그 사실이 행에 드러나고, 화면이 「이 공장에 걸린 규칙」을 그대로 보여 줄 수 있다.
+   */
+  @Column()
+  @Field({ description: 'Twin instance this rule applies to. There are no global rules.' })
+  instanceId: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'What a person calls this rule.' })
+  name?: string
+
+  /** 어느 관측인가 — 커널의 안정 코드(`Attention.kind`). */
+  @Column()
+  @Field({ description: 'Observed condition kind in kernel vocabulary (Attention.kind).' })
+  attentionKind: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Only at this severity or above: low, medium, high, critical.' })
+  minSeverity?: string
+
+  /**
+   * **조건이 이만큼 이어졌을 때** 올린다.
+   *
+   * 없으면 처음 본 주기에 올린다. 깜빡이는 조건에 현장 지시가 나가는 것을 막는 유일한 칸이다.
+   */
+  @Column({ type: 'int', nullable: true })
+  @Field({ nullable: true, description: 'Propose only after the condition has held this long (ms).' })
+  minHeldMs?: number
+
+  /**
+   * 무엇을 내는가 — **선언된 조치 종류**(`CommandTypeSpec.type`).
+   *
+   * 커널 자극(`CMD`)이 아니다. 자극을 적으면 판정이 「선언되지 않은 조치 종류」로 거절한다 — 그 값은
+   * 모델 상태를 바꾸는 것이고 현장에 나가는 지시가 아니다.
+   */
+  @Column()
+  @Field({ description: 'Declared command type to propose. Not a kernel stimulus.' })
+  commandType: string
+
+  /**
+   * 지시의 내용 — `{이름}` 을 관측의 값으로 바꿔 넣는다.
+   *
+   * 바꿀 값은 `Attention.params` 와 `anchor` 에서 온다. 바꿀 것이 없으면 그 칸을 비우고, 요구하는 칸이
+   * 비면 판정이 거절한다 — 지어낸 값으로 현장 지시를 만들지 않는다.
+   */
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Command payload template. {name} is filled from the observation.' })
+  payloadTemplate?: any
+
+  /**
+   * **한 번 낸 근거에 다시 내기까지 기다리는 시간(ms).**
+   *
+   * 비워 두면 기본값이 걸린다(한 시간). 0 으로 두면 기다리지 않는데, 그러면 승인하는 순간 같은 것이
+   * 다시 올라온다 — 걸어 보고 실제로 그 상태를 만들었다.
+   */
+  @Column({ type: 'int', nullable: true })
+  @Field({ nullable: true, description: 'Wait this long before proposing again for the same cause (ms).' })
+  cooldownMs?: number
+
+  /** 지우지 않고 끌 수 있어야 한다 — 잘못 낸 것을 본 사람이 가장 먼저 하려는 일이다. */
+  @Column({ default: true })
+  @Field({ nullable: true, description: 'A disabled rule is not evaluated. Turning off is not deleting.' })
+  enabled?: boolean
+
+  /* ── 마지막 판정의 기록 ─────────────────────────────────────────────────
+   * 규칙이 **아무것도 올리지 않을 때** 사람이 알 수 있어야 한다. 조용히 안 도는 규칙과 조건이 없어서 안
+   * 올리는 규칙은 화면에서 똑같이 보이고, 그 둘을 구별하지 못하면 사람은 규칙이 도는 줄 안다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When this rule was last evaluated (ISO 8601).' })
+  lastRunAt?: string
+
+  @Column({ type: 'int', nullable: true })
+  @Field({ nullable: true, description: 'How many commands this rule has proposed in total.' })
+  proposedCount?: number
+
+  /** 마지막에 왜 안 올렸나 — 사람 말로. */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Why the last evaluation proposed nothing, when it did not.' })
+  lastSkipReason?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true })
+  creator?: User
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true })
+  updater?: User
+
+  @CreateDateColumn()
+  @Field({ nullable: true })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true })
+  updatedAt?: Date
+}

package/server/service/actuation/approval-gateway.ts

@@ -0,0 +1,44 @@
+/*
+ * **승인을 누가 받는가** — 그 자리를 밖으로 낸다.
+ *
+ * ── 왜 시임인가 (2026-08-31) ─────────────────────────────────────────────
+ * 승인은 이미 이 저장소에 있다. `@things-factory/worklist` 가 결재선·위임·상신·「내가 승인할 것」 목록과
+ * 승인 화면까지 들고 있다. 그것을 다시 만들면 두 벌이 되고, 사고 뒤에 「어느 쪽 기록이 진짜인가」를
+ * 묻게 된다.
+ *
+ * 그런데 headless-twin 은 worklist 를 부를 수 없다 — worklist 는 조직도(Employee·Department·Role)와
+ * 화면 27쪽을 데리고 오는 업무 모듈이고, 이 패키지는 커널을 안는 헤드리스 서버다. 의존을 그 방향으로
+ * 걸면 커널을 쓰는 모든 배포가 조직도를 지게 된다.
+ *
+ * 그래서 **이 패키지는 자리만 만들고, 앱이 채운다**(operato-twin). 채우지 않은 배포에서는 게이트가
+ * 사라지지 않는다 — 승인 없이 지나가는 것이 아니라, 아래 §`twinCommands` 의 직접 결정이 유일한 문이 된다.
+ */
+import type { StoredCommand } from './command-dispatcher.js'
+
+/** 결재선에 올리는 자리 — 앱이 구현한다. */
+export interface ApprovalGateway {
+  /** 화면과 오류 문장에 쓰는 이름. 「어디서 승인하는가」를 사람에게 말해야 한다. */
+  label: string
+  /**
+   * 이 커맨드를 결재선에 올린다.
+   *
+   * 돌려주는 것은 **올라간 자리의 식별자**다. 이 값이 커맨드 행에 적히고, 그 뒤로는 직접 결정이 막힌다
+   * — 문이 두 벌이면 한쪽 기록에만 남는 승인이 생긴다.
+   *
+   * `context` 는 리졸버 문맥 그대로 넘긴다(트랜잭션·로그인한 사람·테넌트). 이 패키지가 그 모양을 알면
+   * 앱의 인증 구조를 여기서 다시 정의하게 된다.
+   */
+  request(command: StoredCommand, context: any): Promise<string>
+}
+
+let gateway: ApprovalGateway | undefined
+
+/** 앱이 부팅에서 한 번 부른다. */
+export function setApprovalGateway(next: ApprovalGateway): void {
+  gateway = next
+}
+
+/** 등록된 것이 없으면 `undefined` — 없음을 없음으로 답한다. */
+export function approvalGateway(): ApprovalGateway | undefined {
+  return gateway
+}