@things-factory/headless-twin 10.1.278 → 10.1.279

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

@@ -1,147 +0,0 @@
-/*
- * 규칙을 만들고 끄는 자리, 그리고 **지금 한 번 돌려 보는 자리**.
- *
- * ── 왜 「지금 돌린다」가 있나 ────────────────────────────────────────────
- * 규칙을 만든 사람이 가장 먼저 묻는 것은 「이게 걸리나」다. 주기를 기다려 보라고 하면 그 사이에 무엇이
- * 잘못됐는지 알 수 없고, 조건이 그때까지 살아 있을지도 모른다. 돌려 보면 **무엇을 냈고 무엇을 왜 안
- * 냈는지**가 그 자리에서 답으로 온다.
- */
-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

@@ -1,139 +0,0 @@
-/*
- * **어느 관측에 어느 지시를 붙이는가** — 선언 한 행.
- *
- * ── 왜 표인가 (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

@@ -1,44 +0,0 @@
-/*
- * **승인을 누가 받는가** — 그 자리를 밖으로 낸다.
- *
- * ── 왜 시임인가 (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
-}

package/server/service/actuation/catch-up-effects.ts

@@ -1,152 +0,0 @@
-/*
- * **놓친 보고를 backfill 한다** — 유입 자리에서 잇는 길(§`settle-effects.ts`)의 짝.
- *
- * ── 왜 필요한가 (2026-09-02, 실제로 하나 놓쳤다) ──────────────────────────────
- * 유입 자리에서만 이으면, **우리가 못 듣고 있던 동안 온 보고는 영원히 사라진다.**
- *
- *   10:13  MES 가 WO-20260902-005 를 현장에 냄. order.status 가 트윈에 도착
- *   19:21  잇는 배선을 산출물에 넣음
- *   → 그 보고는 저널에 남았는데 조치에는 안 이어졌다. 다시 오지 않는다
- *
- * 같은 일이 트윈이 내려가 있는 사이, 커넥터를 고치는 사이, 프로세스가 죽었다 서는 사이에 난다.
- * 관측은 되풀이해 주지 않는다.
- *
- * ── 왜 저널을 읽나 ───────────────────────────────────────────────────────────
- * 저널에 `orderId` 가 **컬럼으로** 있고 인덱스도 있다(`ix_twin_event_4 (domain, instanceId, orderId)`
- * — 「이 오더가 어디까지 갔나」). 그래서 「우리가 낸 지시들의 마지막 보고」를 값싸게 물을 수 있다.
- * JSON 안을 뒤지지 않으므로 드라이버 다섯에서 같이 돈다.
- *
- * ── 왜 방향이 반대인가 ───────────────────────────────────────────────────────
- * 유입 쪽은 **보고에서 조치를 찾는다**(보고가 많고 조치가 적다 — 그래서 식별자를 모아 한 번 묻는다).
- * 이쪽은 **조치에서 보고를 찾는다.** 효과를 기다리는 조치는 몇 건이고, 그 몇 건의 식별자로 저널을
- * 물으면 끝난다. 저널 전체를 주사하지 않는다.
- */
-import { OP_EVENT } from '@operato/ops-contract'
-
-import { getRepository } from '@things-factory/shell'
-
-import { twinWarn } from '../../engine/log.js'
-import { TwinEvent } from '../twin-event/twin-event.js'
-
-import type { CommandStore, StoredCommand } from './command-dispatcher.js'
-import { matchEffects, type OrderObservation } from './effect-match.js'
-
-export interface CatchUpResult {
-  /** 효과를 기다리던 조치 수. */
-  awaiting: number
-  /** 이번에 효과를 적은 조치 수. */
-  recorded: number
-  /** 저널에 보고가 아직 없던 조치 수 — 저쪽이 아직 아무 말도 안 한 것이다. */
-  silent: number
-}
-
-/**
- * 이 도메인에서 놓친 보고를 한 번 backfill 한다.
- *
- * **던지지 않는다.** 주기에서 부르고, 여기서 터지면 그 주기가 멈춘다. 그리고 이 일은 다음 바퀴에
- * 다시 해도 같은 결과가 나온다 — 급할 것이 없다.
- */
-export async function catchUpEffects(domainId: string, store: CommandStore): Promise<CatchUpResult> {
-  const none: CatchUpResult = { awaiting: 0, recorded: 0, silent: 0 }
-
-  if (!store.awaitingEffect || !store.recordEffects) {
-    twinWarn(
-      '[actuation] 놓친 보고를 backfill 할 수 없다 — 저장소에 awaitingEffect 나 recordEffects 가 없다. ' +
-        '못 듣고 있던 동안 온 보고는 영원히 이어지지 않는다.'
-    )
-    return none
-  }
-
-  try {
-    const commands = await store.awaitingEffect(domainId)
-    if (!commands.length) return none
-
-    /* 트윈마다 묶는다 — 저널 질의가 트윈 단위로 인덱스를 탄다. */
-    const byTwin = new Map<string, StoredCommand[]>()
-    for (const c of commands) {
-      if (!c.dispatchRef) continue
-      const list = byTwin.get(c.instanceId) ?? []
-      list.push(c)
-      byTwin.set(c.instanceId, list)
-    }
-
-    let recorded = 0
-    let silent = 0
-
-    for (const [instanceId, list] of byTwin) {
-      const observations = await latestOrderReports(
-        domainId,
-        instanceId,
-        list.map(c => c.dispatchRef!)
-      )
-
-      const seen = new Set(observations.map(o => o.orderId))
-      silent += list.filter(c => !seen.has(c.dispatchRef!)).length
-
-      const { updates } = matchEffects({
-        observations,
-        byRef: new Map(
-          list.map(c => [c.dispatchRef!, { id: c.id, dispatchRef: c.dispatchRef!, ...(c.effect ? { effect: c.effect } : {}) }])
-        )
-      })
-
-      /*
-       * **이미 적힌 것과 같으면 적지 않는다.** 주기마다 부르므로, 안 걸러 내면 같은 보고로 `seen` 이
-       * 영원히 는다 — 「몇 번 보고됐나」가 「몇 번 backfill 했나」가 된다.
-       */
-      const changed = updates.filter(u => {
-        const before = list.find(c => c.id === u.commandId)?.effect
-        return !before || before.status !== u.status || before.at !== u.at
-      })
-
-      if (changed.length) {
-        await store.recordEffects(domainId, changed)
-        recorded += changed.length
-      }
-    }
-
-    return { awaiting: commands.length, recorded, silent }
-  } catch (e: any) {
-    twinWarn(`[actuation] 놓친 보고를 backfill하다 실패했다 — ${String(e?.message ?? e).slice(0, 200)}`)
-    return none
-  }
-}
-
-/**
- * 이 트윈에서 그 오더들의 **마지막** 상태 보고를 읽는다.
- *
- * ── 왜 오더마다 따로 묻나 ──────────────────────────────────────────────────
- * 한 번에 묶어 물으면 그 오더들의 보고를 **전부** 받게 된다. 오더 하나가 수백 번 보고될 수 있고
- * (초안 → 나감 → 진행 → 완료, 그리고 수량이 바뀔 때마다), 그러면 상한 없이 저널을 읽는 자리가 된다.
- *
- * 그래서 오더마다 `take: 1` 로 최신 하나만 읽는다. 질의 수가 조치 수만큼 늘지만, **효과를 기다리는
- * 조치는 몇 건**이다(넘긴 것만, 그것도 식별자가 있는 것만). 몇 건에 몇 질의는 값이 아니고, 상한 없이
- * 원장을 읽는 것은 값이다.
- *
- * `revision` 내림차순이 「나중」의 정본이다 — 시각이 같은 보고가 여럿 올 수 있고(같은 밀리초에 둘이
- * 실제로 있었다), 그때 무엇이 나중인지는 원장의 순서가 답한다.
- */
-async function latestOrderReports(
-  domainId: string,
-  instanceId: string,
-  refs: readonly string[]
-): Promise<OrderObservation[]> {
-  const out: OrderObservation[] = []
-  const repo = getRepository(TwinEvent)
-
-  for (const orderId of new Set(refs)) {
-    const rows = await repo.find({
-      where: { domain: { id: domainId }, instanceId, eventType: OP_EVENT.order, orderId },
-      order: { revision: 'DESC' },
-      take: 1
-    } as any)
-
-    const row: any = rows[0]
-    const data = row?.payload?.data
-    if (!data) continue
-
-    /* 봉투에 적힌 시각을 쓴다 — 저장 시각이 아니다. 없으면 판정이 거른다. */
-    out.push({ orderId, status: String(data.status ?? ''), at: row.payload?.eventTime })
-  }
-  return out
-}