@things-factory/headless-twin 10.0.18 → 10.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/headless-twin",
-  "version": "10.0.18",
+  "version": "10.0.19",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh <heartyoh@hatiolab.com>",
@@ -27,12 +27,12 @@
     "clean:shared": "rm -rf dist-shared tsconfig.shared.tsbuildinfo"
   },
   "dependencies": {
-    "@operato/ops-contract": "^0.6.0",
-    "@operato/twin-kernel": "^0.9.0",
-    "@things-factory/auth-base": "^10.0.18",
-    "@things-factory/cache-service": "^10.0.18",
+    "@operato/ops-contract": "^0.8.1",
+    "@operato/twin-kernel": "^0.10.1",
+    "@things-factory/auth-base": "^10.0.19",
+    "@things-factory/cache-service": "^10.0.19",
     "@things-factory/env": "^10.0.8",
-    "@things-factory/shell": "^10.0.18"
+    "@things-factory/shell": "^10.0.19"
   },
-  "gitHead": "806c7af400517177f1323645df03558451587533"
+  "gitHead": "5c170a55152cfe906fe6dbc30e6bfe474ed64122"
 }

package/server/routes.ts

@@ -18,6 +18,7 @@
 import { ingestCanonicalRecords } from './engine/canonical-ingest.js'
 import { TwinEngine } from './engine/twin-engine.js'
 import { handleHook } from './service/reference/reference-hook.js'
+import { databaseStore } from './service/reference/hook-store.js'
 
 process.on('bootstrap-module-domain-public-route' as any, (_app: any, router: any) => {
   /*
@@ -39,6 +40,12 @@ process.on('bootstrap-module-domain-public-route' as any, (_app: any, router: an
       instanceId: String(ctx.params.instanceId ?? ''),
       headers: (ctx.request?.headers ?? {}) as Record<string, unknown>,
       body: ctx.request?.body,
+      /*
+       * 받은 바이트 그대로 — 서명을 확인하려면 이것이 있어야 한다. `koa-bodyparser` 가 파싱한 본문과
+       * 함께 남겨 준다. 파싱본을 다시 문자열로 만들면 키 순서와 공백이 달라져 서명이 맞지 않는다.
+       */
+      rawBody: typeof ctx.request?.rawBody === 'string' ? ctx.request.rawBody : undefined,
+      store: databaseStore(),
       /*
        * 폴링이 쓰는 길을 그대로 쓴다 — 검증도 유입도 같은 자리다. 그래서 트윈 쪽에서는 물어서 받은
        * 것과 밀어 받은 것이 구별되지 않는다. 구별되는 것은 유입 장부의 `sources` 한 줄뿐이다.
@@ -59,7 +66,11 @@ process.on('bootstrap-module-domain-public-route' as any, (_app: any, router: an
          */
         const undelivered = Math.max(0, accepted.length - applied - duplicates)
         TwinEngine.recordIngestResult(domain.id, instanceId, records.length, rejected, Date.now(), undelivered)
-        return { applied, duplicates, rejected: rejected.length }
+        /*
+         * 떨어진 것을 **수가 아니라 목록으로** 넘긴다 — 응답에 실어야 보내는 쪽이 그것만 따로 둘 수
+         * 있다. 수만 주면 배치 전체를 다시 보내거나 전부 버리는 두 갈래밖에 없다.
+         */
+        return { applied, duplicates, rejected }
       }
     })
     ctx.status = outcome.status

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

@@ -0,0 +1,130 @@
+/*
+ * **승인을 지난 커맨드만 어댑터에 넘긴다** — 게이트가 서는 자리.
+ *
+ * ── 왜 이 자리인가 (2026-08-31) ──────────────────────────────────────────
+ * 설계가 「기본 = propose-only」를 정해 두었는데 코드에 그 규율이 없었다. 인티그레이션 레인이 어댑터에
+ * 조치를 붙이려다 그것을 보고 멈췄다 — 게이트 없이 붙이면 트윈이 사람 승인 없이 현장에 작업지시를
+ * 내린다. 작업지시는 취소해도 이미 만든 것이 남는다.
+ *
+ * ── 확인을 여기서 한 번만 한다 ───────────────────────────────────────────
+ * 어댑터는 승인을 확인하지 않는다. 그 확인은 이 파일이 했고 **타입이 그것을 증명한다**
+ * (`ApprovedCommand` 는 `approveCommand`·`asApproved` 로만 만들어진다). 어댑터가 또 확인하면 규칙이
+ * 두 벌이 되고, 한쪽만 고쳐지는 날이 온다.
+ *
+ * ── 저장소에 닿는 자리를 밖으로 낸다 ─────────────────────────────────────
+ * 훅에서와 같은 이유다(§`HookStore`). 시험이 **재기동을 넣을 수 있어야** 한다 — 승인이 프로세스 안에만
+ * 살아 있으면 「승인된다」는 보이지만 「다시 세운 뒤에도 승인이 남아 있나」는 보이지 않는다.
+ */
+import {
+  approveCommand,
+  asApproved,
+  nextCommandState,
+  passThroughReversible,
+  requiresApproval,
+  type ApprovedCommand,
+  type CommandApproval,
+  type TwinCommand
+} from '@operato/ops-contract'
+
+/** 조치의 결과 — 어댑터가 돌려준다. */
+export interface CommandAck {
+  ok: boolean
+  /** 저쪽 문서 · 작업 식별자. 되돌릴 때 무엇을 되돌릴지 말하려면 이것이 있어야 한다. */
+  ref?: string
+  error?: string
+}
+
+/** 커맨드가 사는 자리 — 재기동을 넘어야 한다. */
+export interface CommandStore {
+  load(domainId: string, id: string): Promise<TwinCommand | null>
+  save(domainId: string, command: TwinCommand): Promise<void>
+}
+
+/**
+ * 승인한다.
+ *
+ * 승인할 수 없는 상태면 계약이 던진다 — 여기서 답으로 돌려주지 않는 이유는, 실패를 답으로 주면 부르는
+ * 쪽이 그것을 무시할 수 있기 때문이다.
+ */
+export async function approve(
+  store: CommandStore,
+  domainId: string,
+  id: string,
+  approval: CommandApproval
+): Promise<TwinCommand> {
+  const command = await store.load(domainId, id)
+  if (!command) throw new Error(`모르는 커맨드다 (${id})`)
+
+  const approved = approveCommand(command, approval)
+  await store.save(domainId, approved)
+  return approved
+}
+
+/** 거절한다 — 여기서 끝난다. 되살아나지 않는다. */
+export async function reject(
+  store: CommandStore,
+  domainId: string,
+  id: string,
+  approval: CommandApproval
+): Promise<TwinCommand> {
+  const command = await store.load(domainId, id)
+  if (!command) throw new Error(`모르는 커맨드다 (${id})`)
+
+  const to = nextCommandState(command.state, 'reject')
+  if (!to) throw new Error(`${command.state} 상태의 커맨드는 거절할 수 없다 (${id})`)
+
+  const next: TwinCommand = { ...command, state: to, approval }
+  await store.save(domainId, next)
+  return next
+}
+
+/**
+ * 어댑터에 넘긴다 — **승인을 지나지 않은 것은 여기서 막힌다.**
+ *
+ * `actuate` 는 `ApprovedCommand` 만 받으므로, 승인 없이 이 함수를 지나가는 길이 없다. 저장소에서
+ * 되세운 커맨드는 타입이 지워진 채로 오므로 `asApproved` 로 다시 확인한다 — 확인 없이 표식을 붙이면
+ * **재기동이 게이트를 여는 길**이 된다.
+ *
+ * 되돌릴 수 있는 커맨드는 사람 없이 지난다(시뮬·what-if). 그 판단도 계약이 한다.
+ */
+export async function dispatch(
+  store: CommandStore,
+  domainId: string,
+  id: string,
+  actuate: (command: ApprovedCommand) => Promise<CommandAck>
+): Promise<TwinCommand> {
+  const command = await store.load(domainId, id)
+  if (!command) throw new Error(`모르는 커맨드다 (${id})`)
+
+  /*
+   * 되돌릴 수 있는 것은 제안 상태에서 바로 지난다. 되돌릴 수 없는 것은 승인 기록이 있어야 하고,
+   * 없으면 여기서 던진다 — 조용히 건너뛰면 그 커맨드가 승인 없이 나간 것이 된다.
+   */
+  const approved: ApprovedCommand =
+    command.state === 'proposed' && !requiresApproval(command) ? passThroughReversible(command) : asApproved(command)
+
+  const to = nextCommandState(approved.state, 'dispatch')
+  if (!to) throw new Error(`${approved.state} 상태의 커맨드는 넘길 수 없다 (${id})`)
+
+  /*
+   * **넘기기 전에 「넘기는 중」을 먼저 적는다.** 넘기고 나서 적으면, 그 사이에 프로세스가 죽었을 때
+   * 저쪽은 받았는데 우리는 안 보낸 줄 알고 다시 보낸다. 현장이 두 번 움직인다.
+   */
+  const dispatching: TwinCommand = { ...approved, state: to }
+  await store.save(domainId, dispatching)
+
+  let ack: CommandAck
+  try {
+    ack = await actuate(approved)
+  } catch (e: any) {
+    const failed: TwinCommand = { ...dispatching, state: 'failed', error: String(e?.message ?? e) }
+    await store.save(domainId, failed)
+    return failed
+  }
+
+  const settled: TwinCommand = ack?.ok
+    ? { ...dispatching, state: 'acked', dispatchRef: ack.ref }
+    : { ...dispatching, state: 'failed', error: ack?.error ?? '어댑터가 이유를 말하지 않았다' }
+  await store.save(domainId, settled)
+  return settled
+}

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

@@ -0,0 +1,62 @@
+/*
+ * 커맨드가 저장소에 닿는 두 자리 — 찾는 것과 적는 것.
+ *
+ * 디스패처가 엔티티를 직접 가져오면 그 파일을 부르는 시험이 TypeORM 데코레이터를 지나게 되고, 시험이
+ * 서지 않는다. 그러면 **게이트의 배선을 아무 시험도 걷지 않게 된다** — 훅에서 이미 겪은 부류다
+ * (§`hook-store.ts`).
+ */
+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 } from './command-dispatcher.js'
+
+/**
+ * 행 → 커맨드. 상태 어휘는 계약이 정한 문자열 그대로다.
+ *
+ * `createdAt` 은 드라이버가 준 값이라 **직접 날짜로 만들지 않는다** — 드라이버마다 모양이 다르고,
+ * 문자열로 오는 드라이버에서는 시간대가 없는 값이 된다. `hydratedDate` 가 그 컬럼의 정의를 보고 푼다.
+ */
+function toCommand(repo: any, row: TwinCommandRecord): TwinCommand {
+  return {
+    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.error ? { error: row.error } : {})
+  }
+}
+
+/** 실제 저장소를 쓰는 구현 — 리졸버가 이것을 넣는다. */
+export function databaseCommandStore(): CommandStore {
+  return {
+    load: async (domainId: string, id: string) => {
+      const repo = await getRepository(TwinCommandRecord)
+      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(
+        { id: command.id, domain: { id: domainId } },
+        {
+          state: command.state,
+          decidedBy: command.approval?.by ?? null,
+          decidedAt: command.approval?.at ?? null,
+          decisionNote: command.approval?.note ?? null,
+          dispatchRef: command.dispatchRef ?? null,
+          error: command.error ?? null
+        } as any
+      )
+    }
+  }
+}

package/server/service/actuation/index.ts

@@ -0,0 +1,8 @@
+import { TwinCommandRecord } from './twin-command.js'
+
+export const entities = [TwinCommandRecord]
+export const resolvers = []
+
+export * from './twin-command.js'
+export * from './command-dispatcher.js'
+export * from './command-store.js'

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

@@ -0,0 +1,105 @@
+/*
+ * **현장에 내리는 조치 하나** — 제안 · 승인 · 넘김 · 응답이 한 행에 남는다.
+ *
+ * ── 왜 표인가 (2026-08-31) ───────────────────────────────────────────────
+ * 승인이 프로세스 안에만 있으면 트윈이 재기동한 순간 승인 대기 줄이 사라진다. 그때 사람은 **자기가
+ * 승인한 것이 실행됐는지 알 수 없다.** 조치는 되돌리기 어려운 것이므로 그 모름이 그대로 사고가 된다.
+ *
+ * 그리고 이 행은 **누가 언제 승인했나**의 기록이기도 하다. 사고 뒤에 그것을 물을 자리가 여기다.
+ *
+ * ── 판정은 여기 없다 ─────────────────────────────────────────────────────
+ * 어느 상태에서 어느 사건이 허용되는지는 계약이 든다(`@operato/ops-contract` §`nextCommandState`).
+ * 이 파일은 그 값을 담기만 한다 — 판정이 두 벌이 되면 화면과 서버가 다른 답을 낸다.
+ */
+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'
+
+@Entity()
+/* 대기 줄을 여는 질의가 이 세 칸으로 묻는다 — 어느 테넌트의 · 어느 트윈의 · 어느 상태인가. */
+@Index('ix_twin_command_0', (e: TwinCommandRecord) => [e.domain, e.instanceId, e.state])
+@ObjectType({ description: 'One actuation command proposed against a twin, with its approval trail.' })
+export class TwinCommandRecord {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the command.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Tenant this command belongs to.' })
+  domain?: Domain
+
+  @RelationId((e: TwinCommandRecord) => e.domain)
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'Twin instance this command acts on.' })
+  instanceId: string
+
+  @Column()
+  @Field({ description: 'Command type in twin vocabulary. Translating it into a legacy call is the adapter job.' })
+  type: string
+
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Command payload in twin vocabulary.' })
+  payload?: any
+
+  @Column()
+  @Field({ description: 'Who proposed it: operator, rule, ai or schedule. A person weighs this when approving.' })
+  origin: string
+
+  /**
+   * **되돌릴 수 있는가** — 게이트가 걸리는 기준이다.
+   *
+   * 비어 있으면 「되돌릴 수 없다」로 읽는다(§`requiresApproval`). 모름을 되돌릴 수 있다로 읽으면 그
+   * 커맨드가 승인 없이 나간다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Whether the effect can be undone. Absent means it cannot, and a person must approve.' })
+  reversible?: boolean
+
+  @Column()
+  @Field({ description: 'proposed · approved · rejected · dispatched · acked · failed.' })
+  state: string
+
+  /* ── 승인의 기록 ─────────────────────────────────────────────────────────
+   * 한 칸에 JSON 으로 담지 않고 세 칸으로 나눈다 — 「누가 승인했나」로 묻는 질의가 실제로 온다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Who approved or rejected it.' })
+  decidedBy?: string
+
+  /*
+   * ISO 문자열로 든다 — `datetime` 은 드라이버 방언이라 다섯 드라이버를 그대로 지나지 못하고,
+   * sqlite 는 그것을 검증하지 않아 개발에서 잡히지 않는다. 이 저장소의 다른 시각 칸도 그 모양이다
+   * (§`TwinReference.lastSyncedAt`). 계약의 `CommandApproval.at` 도 ISO 문자열이라 옮길 것이 없다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When it was approved or rejected (ISO 8601).' })
+  decidedAt?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Why — free text the approver wrote.' })
+  decisionNote?: string
+
+  /**
+   * 어댑터가 돌려준 것 — 저쪽에서 무엇이 되었는지 되짚을 수 있어야 한다.
+   *
+   * 이것이 없으면 되돌릴 때 **무엇을 되돌릴지 말할 수 없다.**
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Reference the adapter returned. Without it a reversal cannot name what to undo.' })
+  dispatchRef?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Why the dispatch failed. The server sentence, kept as it came.' })
+  error?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'When the command was proposed.' })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true, description: 'When the row last changed.' })
+  updatedAt?: Date
+}

package/server/service/index.ts

@@ -31,6 +31,8 @@ import { entities as TwinStructureEntities } from './twin-structure/index.js'
 import { entities as TwinSpaceEntities, resolvers as TwinSpaceResolvers } from './twin-space/index.js'
 import { entities as TwinTargetEntities, resolvers as TwinTargetResolvers } from './twin-target/index.js'
 import { entities as TwinReferenceEntities, resolvers as TwinReferenceResolvers } from './reference/index.js'
+/* 현장에 내리는 조치 — 승인이 재기동을 넘어 살아야 하므로 표로 든다(§`actuation/twin-command.ts`). */
+import { entities as TwinActuationEntities } from './actuation/index.js'
 import { resolvers as TwinStateResolvers } from './twin-state/index.js'
 import { resolvers as TwinControlResolvers } from './twin-control/index.js'
 import { entities as TwinModelEntities, resolvers as TwinModelResolvers } from './twin-model/index.js'
@@ -56,6 +58,7 @@ export const entities = [
   ...TwinSpaceEntities,
   ...TwinTargetEntities,
   ...TwinReferenceEntities,
+  ...TwinActuationEntities,
   /* 구조 투영 — model JSON 에서 풀어낸 표준 엔티티(ADR-0032). 원본에서 온 캐시. */
   ...TwinModelEntities
 ]

package/server/service/reference/hook-contract.ts

@@ -42,6 +42,8 @@
  * 경계가 이미 거릅니다(§`FactDeduper`) — 이 파일이 따로 하지 않습니다. 응답에 몇 건이 중복이었는지
  * 함께 알립니다.
  */
+import { WEBHOOK_HEADER, verifyWebhookSignature } from '@operato/ops-contract/webhook'
+
 /** 훅 요청의 결과 — 상태 코드와 본문을 함께 정한다(부르는 쪽이 그대로 답한다). */
 export interface HookOutcome {
   status: number
@@ -49,28 +51,18 @@ export interface HookOutcome {
 }
 
 /**
- * 응답 코드 규약 — **재시도로 해결되는 것과 그렇지 않은 것을 가른다.**
- *
- * 밀어 주는 쪽은 응답 코드로 재시도를 정합니다. 그래서 우리가 코드를 아무렇게나 주면 두 가지가
- * 일어납니다: 고칠 수 없는 것을 영원히 다시 보내거나, 잠깐의 문제로 사라진 사실을 아무도 모릅니다.
- *
- *   200  받아서 반영했다
- *   401  비밀값이 다르다                    재시도해도 같다
- *   404  모르는 연결이거나 모르는 트윈       재시도해도 같다
- *   400  본문을 우리 레코드로 옮길 수 없다   재시도해도 같다(그쪽 모양이 바뀐 것이다)
- *   409  그 트윈이 지금 실시간으로 돌지 않는다  사람이 트윈을 띄워야 한다
- *   501  그 커넥터가 훅을 받을 줄 모른다      코드가 없다
- *   500  우리 쪽 오류                        재시도하면 될 수 있다
+ * 응답 코드 규약 — **계약이 정하고 여기서는 그것을 쓴다**(2026-08-31).
+ *
+ * 예전에는 이 표가 여기 있었고 보내는 쪽(operato-mes)에 또 있었다. 그래서 같은 409 를 양쪽이 다른
+ * 뜻으로 썼다 — 여기서는 「그 트윈이 실시간으로 돌지 않는다」, 저쪽에서는 「번호가 비었다」였다.
+ * 붙였다면 트윈이 안 도는 동안 보내는 쪽이 같은 구간을 계속 다시 보냈다.
+ *
+ * 판정표는 만드는 쪽과 읽는 쪽이 합의해야 하는 것이라 계약 층에 있다(`@operato/ops-contract`).
+ * `notLive` 가 409 에서 503 으로 옮겨진 이유도 그 파일에 적혀 있다.
+ *
+ * **여기서 이름을 바꿔 다시 내보내지 않는다.** 부르는 쪽은 `WEBHOOK_STATUS` 를 계약에서 바로 가져온다.
+ * 별명을 두면 같은 표에 이름이 둘이 되고, 다음 사람이 어느 쪽이 정본인지 물어야 한다.
  */
-export const HOOK_STATUS = {
-  ok: 200,
-  badSecret: 401,
-  unknownTarget: 404,
-  badPayload: 400,
-  notLive: 409,
-  unsupported: 501,
-  failed: 500
-} as const
 
 /** 헤더에서 비밀값을 꺼낸다 — 두 가지 방식을 받는다(밀어 주는 쪽의 관습이 갈린다). */
 export function secretFromHeaders(headers: Record<string, unknown> | undefined): string {
@@ -94,6 +86,92 @@ export function secretMatches(given: string, expected: string): boolean {
   return diff === 0
 }
 
+/**
+ * 인증 — **서명이 왔으면 서명을 보고, 아니면 비밀값을 본다.**
+ *
+ * 두 방식을 두는 이유는 밀어 주는 쪽의 사정이 다르기 때문이다. 이미 붙어 있는 커넥터는 비밀값을 헤더에
+ * 싣는 방식으로 만들어졌고, 새로 만드는 것(operato-mes)은 서명을 쓴다. 서명 쪽이 낫다 — 비밀값을 그대로
+ * 싣는 방식은 그 요청을 그대로 다시 보내는 것을 막지 못한다.
+ *
+ * **서명이 왔는데 확인할 수 없으면 거절한다.** 받은 바이트를 들고 있지 않으면(`rawBody` 가 없으면)
+ * 파싱한 객체를 다시 문자열로 만들어 확인하고 싶어지는데, 키 순서와 공백이 달라져 어차피 맞지 않는다.
+ * 맞지 않는 것을 통과시키면 서명이 있으나 마나 한 것이 된다.
+ */
+export function authorizeHook(args: {
+  headers: Record<string, unknown> | undefined
+  /** 받은 바이트 그대로. 서명을 쓰지 않는 연결에서는 없어도 된다. */
+  rawBody: string | undefined
+  /** 연결 설정에 저장된 비밀값. 서명과 비밀값이 같은 값을 쓴다. */
+  secret: string
+  nowMs: number
+}): { ok: true; method: 'signature' | 'secret' } | { ok: false; reason: string } {
+  const { headers, rawBody, secret, nowMs } = args
+  const pick = (k: string) => String((headers ?? {})[k] ?? '').trim()
+  const signature = pick(WEBHOOK_HEADER.signature)
+
+  if (signature) {
+    if (rawBody === undefined) {
+      return { ok: false, reason: 'signed request but the raw body was not kept — cannot verify' }
+    }
+    const verdict = verifyWebhookSignature({
+      secret,
+      timestamp: pick(WEBHOOK_HEADER.timestamp),
+      signature,
+      body: rawBody,
+      nowMs
+    })
+    /* `=== false` 로 본다 — 이 저장소는 `strictNullChecks` 가 꺼져 있어 참·거짓만으로는 좁혀지지 않는다. */
+    if (verdict.ok === false) return { ok: false, reason: `signature ${verdict.reason}` }
+    return { ok: true, method: 'signature' }
+  }
+
+  return secretMatches(secretFromHeaders(headers), secret)
+    ? { ok: true, method: 'secret' }
+    : { ok: false, reason: 'hook secret does not match' }
+}
+
+/**
+ * 커서에 적을 열쇠 — **트윈까지 넣는다.**
+ *
+ * ── 왜 (2026-08-31, MES 레인 질문에서 나옴) ───────────────────────────────
+ * 커서는 **연결마다** 한 행(`TwinReference.liveCursor`)에 산다. 그런데 연결 하나가 트윈 여럿을
+ * 만든다(`scopeSpec.produced` 가 목록이다). 보내는 쪽의 단위 이름만으로 열쇠를 잡으면, 같은 연결의
+ * 두 공장이 같은 이름(`EVENTS`)을 쓸 때 **한 계수기를 함께 쓴다.**
+ *
+ * 그러면 A 공장이 5까지 올린 뒤 B 공장이 1을 보내면 이미 본 번호가 되어 버려지고, A 가 6을 보내면
+ * B 의 번호와 어긋나 끊임없이 「빠졌다」가 된다. 같은 부류가 이 저장소에서 이미 났다 — 두 공장의
+ * 같은 번호가 한 자리에 겹쳤다.
+ *
+ * 보내는 쪽에 트윈 이름을 넣으라고 하지 않는다. 어디로 갈지는 주소가 이미 말했고, 그것을 본문에도
+ * 적으라고 하면 둘이 어긋나는 날 어느 쪽을 믿을지 정해야 한다.
+ */
+export function pushCursorKey(instanceId: string, scope: string): string {
+  return `${instanceId}::${scope}`
+}
+
+/**
+ * 커서에서 그 단위의 마지막 번호를 꺼낸다.
+ *
+ * 커서 모양은 `{ streams: { [흐름]: { since?, seen[], seq? } } }` 이고 **흐름 이름은 어댑터가 정한다**
+ * (§`TwinReference.liveCursor`). 밀어 주는 연결에서는 그 이름이 곧 번호를 매기는 단위다.
+ *
+ * 자리를 따로 만들지 않는 이유는 「재기동을 넘어 사는 진행 위치」가 두 벌이 되기 때문이다. 폴링이 쓰는
+ * `since` 와 밀어 주기가 쓰는 `seq` 는 둘 다 「이 흐름을 어디까지 읽었나」이고 원본이 되풀어 줄 수 있다.
+ */
+export function seqOf(cursor: unknown, scope: string): number | undefined {
+  const streams = (cursor as any)?.streams
+  const seq = streams?.[scope]?.seq
+  return typeof seq === 'number' && Number.isInteger(seq) ? seq : undefined
+}
+
+/** 그 단위의 번호만 바꾼 커서를 만든다 — 다른 흐름과 `since`·`seen` 은 그대로 둔다. */
+export function withSeq(cursor: unknown, scope: string, seq: number): Record<string, unknown> {
+  const base = (cursor && typeof cursor === 'object' ? (cursor as Record<string, unknown>) : {}) as Record<string, any>
+  const streams = base.streams && typeof base.streams === 'object' ? { ...base.streams } : {}
+  streams[scope] = { ...(streams[scope] ?? {}), seq }
+  return { ...base, streams }
+}
+
 /** 이 연결이 이 트윈을 만들었나 — 남의 트윈에 밀어 넣지 못하게. */
 export function producedInstance(ref: { scopeSpec?: any } | null | undefined, instanceId: string): { siteId: string } | undefined {
   const produced: any[] = (ref?.scopeSpec as any)?.produced ?? []

package/server/service/reference/hook-store.ts

@@ -0,0 +1,28 @@
+/*
+ * 훅이 저장소에 닿는 두 자리 — 연결을 찾는 것과 커서를 적는 것.
+ *
+ * ── 왜 갈라져 있나 (2026-08-31) ──────────────────────────────────────────
+ * `reference-hook.ts` 가 엔티티를 직접 가져오면 그 파일을 부르는 시험이 TypeORM 데코레이터를 지나게
+ * 되고, 시험이 서지 않는다. 실제로 훅 시험이 규약 파일(`hook-contract.ts`)만 부르고 있었던 이유가
+ * 그것이다 — 그래서 **배선은 아무 시험도 걷지 않았다.**
+ *
+ * 저장소에 닿는 두 함수만 여기로 내면, 처리 순서 전체를 시험이 같은 함수로 걸을 수 있다. 시험은
+ * 저장본을 손에 들고 있는 구현을 넣어 재기동까지 넣는다.
+ */
+import { getRepository } from '@things-factory/shell'
+
+import { TwinReference } from './twin-reference.js'
+import type { HookStore } from './reference-hook.js'
+
+/** 실제 저장소를 쓰는 구현 — 라우터가 이것을 넣는다. */
+export function databaseStore(): HookStore {
+  return {
+    load: (domainId: string, source: string) =>
+      getRepository(TwinReference)
+        .findOne({ where: { domain: { id: domainId }, source } })
+        .catch(() => null),
+    saveCursor: async (refId: string, cursor: unknown) => {
+      await getRepository(TwinReference).update({ id: refId }, { liveCursor: cursor } as any)
+    }
+  }
+}

package/server/service/reference/reference-adapter.ts

@@ -1,3 +1,5 @@
+import type { ApprovedCommand } from '@operato/ops-contract'
+
 import type { ReferenceStep } from './reference-progress.js'
 import type { ReferenceMaster } from './reference-master.js'
 import { twinWarn } from '../../engine/log.js'
@@ -5,7 +7,8 @@ import { twinWarn } from '../../engine/log.js'
 /*
  * 레퍼런스 어댑터 계약 (reference-management P1) — 정적 마스터 등록(`registerReference`)을
  * "어댑터 타입" 등록으로 일반화한다. 레퍼런스 = 데이터(TwinReference 행), 어댑터 = 동작.
- * inbound 전용(구조·상태 유입). 아웃바운드 액추에이션은 command-routing(별도 ActuationAdapter) 소유.
+ * 아웃바운드 액추에이션은 **별개 어댑터가 아니라 이 어댑터의 반대 면**이다(`actuate`) — 같은 연결이
+ * 사실을 읽고 조치를 내리므로 인증과 설정이 한 자리에 있어야 한다(command-routing §8.1).
  * seam: openLiveFeed 레코드 → 커널 face2-adapter.ingest → CanonicalEnvelope 까지가 여기,
  *       이후 projector 구동은 face2-inbound-live 소유.
  * 설계 SoT: operato-twin/design/plans/reference-management.md §2.2·§4.2.
@@ -163,6 +166,43 @@ export interface ObservedItemFact {
   lot?: string
 }
 
+/**
+ * 밀어 받은 본문 하나를 옮긴 결과 (2026-08-31).
+ *
+ * 레코드만 돌려주던 것을 넓혔다. 번호를 함께 받아야 프레임워크가 빠진 것을 알아챈다.
+ *
+ * **`scope` 가 없으면 `seq` 도 없는 것으로 다룬다.** 번호만 있고 그 번호가 어느 줄의 것인지 모르면
+ * 커서를 무엇으로 잡을지 짐작해야 하고, 짐작한 열쇠는 보내는 쪽이 줄을 하나 더 늘리는 날 어긋난다.
+ * 실제로 operato-mes 가 `[domain, channel]` 마다 번호를 매기면서 봉투에 `channel` 을 싣지 않고 있었다.
+ */
+export interface InboundBatch {
+  /**
+   * 옮긴 것들. 우리와 무관한 본문이면 빈 배열이다.
+   *
+   * **한 요청에 봉투가 여럿 온다.** 밀어 주는 쪽은 한 건씩 보내지 않는다 — 번호도 봉투마다 붙는다.
+   * 배치를 대표하는 번호 하나로는 가운데가 빠진 것을 알아채지 못한다.
+   */
+  items: InboundItem[]
+  /**
+   * 이 요청의 번호가 어느 줄의 것인가. 번호를 매기지 않는 원본은 주지 않는다.
+   *
+   * 요청 하나가 한 줄에만 속한다 — 한 요청에 두 줄을 섞으면 어느 줄의 어디까지 받았는지를 응답
+   * 하나로 말할 수 없다.
+   */
+  scope?: string
+}
+
+export interface InboundItem {
+  /** 우리 어휘로 옮긴 레코드 하나. */
+  record: unknown
+  /**
+   * 이 봉투의 번호.
+   *
+   * **한 배치 안에서 있거나 없거나 하나로 통일한다.** 섞이면 빠진 것이 있는지 판단할 근거가 없다.
+   */
+  seq?: number
+}
+
 /**
  * 재기동을 넘어 이어지는 읽기 상태 — 참조 계층이 소유하고 어댑터에 건넨다(§`openLiveFeed`).
  *
@@ -366,8 +406,33 @@ export interface ReferenceAdapter {
    * ── 판단은 여기서 한다 ────────────────────────────────────────────────────
    * 통신이 끊긴 설비의 값을 보내지 않는 것, 잰 시각이 나아가지 않은 줄을 거르는 것 — 폴링에서 하던
    * 판단을 여기서도 한다. 그래야 두 길이 같은 답을 낸다.
+   *
+   * ── 번호는 프레임워크가 본다 (2026-08-31) ─────────────────────────────────
+   * 빠진 번호를 알아채는 일은 밀어 주는 모든 연결에 같은 규율이라야 한다. 커넥터마다 만들면 한 곳이
+   * 빠지고, 빠진 그 연결에서만 사실이 없어진다. 그래서 커넥터는 **번호를 꺼내 주기만** 하고 판정은
+   * 프레임워크가 한다(§`reference-hook`).
+   */
+  handleInbound?(cfg: ConnectionConfig, site: { siteId: string }, body: unknown, headers: Record<string, unknown>): InboundBatch
+
+  /**
+   * **현장에 조치를 내린다** — 인바운드의 반대 면(§`command-routing.md` §8.1).
+   *
+   * 별개 어댑터를 두지 않는다. 같은 연결이 사실을 읽고 조치를 내리므로, 인증과 설정이 한 자리에 있어야
+   * 한다. 둘로 나누면 같은 시스템에 두 벌의 연결 설정이 생긴다.
+   *
+   * ── 승인은 이미 지났다 (2026-08-31) ───────────────────────────────────────
+   * 인자가 `ApprovedCommand` 다 — 그 표식은 승인을 지난 커맨드에만 붙고, 디스패처가 붙인다
+   * (§`command-dispatcher.ts`). **어댑터는 승인을 다시 확인하지 않는다.** 확인이 두 곳에 있으면
+   * 규칙이 두 벌이 되고 한쪽만 고쳐지는 날이 온다.
+   *
+   * 이 자리를 게이트보다 먼저 열지 않은 이유가 있다 — 자리가 있으면 누군가 부르고, 그때 사람 승인 없이
+   * 현장에 작업지시가 나간다. 작업지시는 취소해도 이미 만든 것이 남는다.
+   *
+   * ── 돌려줄 것 ─────────────────────────────────────────────────────────────
+   * `ref` 를 **반드시** 돌려준다. 그것이 없으면 넘긴 것이 저쪽에서 무엇이 되었는지 되짚을 수 없고,
+   * 되돌릴 때 무엇을 되돌릴지 말할 수 없다.
    */
-  handleInbound?(cfg: ConnectionConfig, site: { siteId: string }, body: unknown, headers: Record<string, unknown>): unknown[]
+  actuate?(cfg: ConnectionConfig, site: SiteDescriptor, command: ApprovedCommand): Promise<{ ok: boolean; ref?: string; error?: string }>
 
   openLiveFeed?(
     cfg: ConnectionConfig,