@things-factory/headless-twin 10.1.278 → 10.1.280

package/server/migrations/1786500000000-CreateTwinSubjectEvents.ts

@@ -1,93 +0,0 @@
-import { MigrationInterface, QueryRunner, Table, TableIndex } from 'typeorm'
-
-/**
- * **대상별 사건 목록** — 조회용 파생 표를 만든다.
- *
- * ── 왜 (2026-08-27 실측) ────────────────────────────────────────────────────
- * 360 화면이 「이 대상의 이력」을 묻고 그 조회가 64초다. 「무엇으로 걸러 시각순으로 정렬해 앞에서
- * 30개」라는 모양에 맞는 목차가 저널에 없고, 얹어도 풀리지 않는다.
- *
- *   여러 값으로 거르면(IN) 정렬 때문에 목차를 못 쓴다
- *   축이 늘 때마다 저널의 목차가 늘어난다 — 360 의 축 넷이면 13개가 된다
- *   품목과 로트가 한 문자열에 붙어 있어 품목만으로는 찾을 수 없다
- *
- * ── 비어서 시작한다 ────────────────────────────────────────────────────────
- * 이 표는 **앞으로만 채운다.** 기존 3,128만 건을 소급해서 채우지 않는다 — 그래야 새 조회 축이 필요할
- * 때마다 전체를 다시 만드는 구조가 되지 않는다. 담지 않은 구간은 조회가 `coveredFrom` 으로 말한다.
- *
- * 그래서 이 마이그레이션은 큰 기록에서도 값싸다(표와 목차를 만들 뿐, 채우지 않는다).
- *
- * 멱등이고 TypeORM API 만 쓴다(드라이버 다섯을 다 지나가야 하므로 raw SQL 금지). 컬럼 타입 이름을
- * 적지 않는 규율은 엔티티와 같다 — `datetime` 은 Postgres 가 거절한다.
- *
- * 설계: `operato-twin/design/plans/read-models.md`
- */
-const TABLE = 'twin_subject_events'
-
-export class CreateTwinSubjectEvents1786500000000 implements MigrationInterface {
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    /*
-     * 표마다 따로 본다 — 하나가 이미 있다고 여기서 돌아가면 나머지가 만들어지지 않는다. 실제로 그렇게
-     * 적어 두었다가, 사건 목록만 있고 진행 지점 표가 없는 상태를 만들었다.
-     */
-    if (!(await queryRunner.hasTable(TABLE))) {
-      await this.createSubjectEvents(queryRunner)
-    }
-  }
-
-  private async createSubjectEvents(queryRunner: QueryRunner): Promise<void> {
-    await queryRunner.createTable(
-      new Table({
-        name: TABLE,
-        columns: [
-          { name: 'id', type: 'varchar', length: '36', isPrimary: true },
-          { name: 'domain_id', type: 'varchar', length: '36', isNullable: true },
-          { name: 'instance_id', type: 'varchar', isNullable: false },
-          { name: 'subject_kind', type: 'varchar', isNullable: false },
-          { name: 'subject_id', type: 'varchar', isNullable: false },
-          /* 시각 컬럼의 타입 이름은 드라이버가 정한다 — `timestamp` 는 sqlite 가 모르고 `datetime` 은 Postgres 가 거절한다. */
-          { name: 'event_time', type: queryRunner.connection.driver.mappedDataTypes.createDate as string, isNullable: false },
-          { name: 'revision', type: 'int', isNullable: false },
-          { name: 'event_type', type: 'varchar', isNullable: false },
-          { name: 'event_id', type: 'varchar', length: '36', isNullable: true },
-          {
-            name: 'created_at',
-            type: queryRunner.connection.driver.mappedDataTypes.createDate as string,
-            isNullable: true
-          }
-        ]
-      }),
-      true
-    )
-
-    const table = await queryRunner.getTable(TABLE)
-    if (!table) return
-
-    /* 이 표의 존재 이유 — 「이 대상의 것을 최신순으로」가 목차를 위에서 읽고 끝난다(정렬 없음). */
-    if (!table.indices.some(i => i.name === 'ix_twin_subject_event_0')) {
-      await queryRunner.createIndex(
-        table,
-        new TableIndex({
-          name: 'ix_twin_subject_event_0',
-          columnNames: ['domain_id', 'instance_id', 'subject_kind', 'subject_id', 'event_time']
-        })
-      )
-    }
-    /* 보관 상한을 지우는 축 — 「이 트윈에서 오래된 줄」. */
-    if (!table.indices.some(i => i.name === 'ix_twin_subject_event_1')) {
-      await queryRunner.createIndex(
-        table,
-        new TableIndex({
-          name: 'ix_twin_subject_event_1',
-          columnNames: ['domain_id', 'instance_id', 'event_time']
-        })
-      )
-    }
-
-  }
-
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    if (!(await queryRunner.hasTable(TABLE))) return
-    await queryRunner.dropTable(TABLE)
-  }
-}

package/server/migrations/1786600000000-RenameOperatoMesAdapterType.ts

@@ -1,66 +0,0 @@
-import { MigrationInterface, QueryRunner } from 'typeorm'
-
-/**
- * `twin_references.adapter_type` — `operato-mes` → `operato-plant`.
- *
- * ── 왜 마이그레이션이 필요한가 ────────────────────────────────────────────────
- * 커넥터의 `type` 은 **저장되는 식별자**다. 트윈을 원본에 붙일 때 그 문자열이 이 컬럼에 적히고,
- * 넘길 때·라이브를 열 때 그 값으로 커넥터를 찾는다(§`getAdapter`).
- *
- * 그래서 제품 개명(`operato-mes` → `operato-plant`)이 코드만 바뀌면 **이미 붙어 있는 원본이 커넥터를
- * 못 찾는다.** 그때 나오는 것은 이렇다.
- *
- *   조치 넘김    `no-adapter` 로 거절
- *   라이브       커넥터가 없어 관측이 끊긴다
- *   화면         「등록되지 않은 커넥터입니다 (operato-mes)」 한 줄
- *
- * **오류는 안 나고, 원인이 개명이라는 것이 그 문장에 없다.** 트윈은 그대로 서 있고 값만 안 온다.
- * 이 저장소에서 개명이 저장된 식별자에 닿았을 때 늘 이 모양으로 났다(보드 키·씬 컴포넌트 타입).
- *
- * ── 왜 이 패키지인가 ─────────────────────────────────────────────────────────
- * 표를 든 쪽이 이 패키지다(`twin_references`). 커넥터는 `operato-twin` 이 등록하지만, 그 값이 사는
- * 자리는 여기다. 마이그레이션은 표를 든 패키지에 둔다.
- *
- * ── 되돌리기 ─────────────────────────────────────────────────────────────────
- * `down` 이 값을 되돌린다. 옛 코드로 되돌아가는 경우가 실제로 있고(배포 롤백), 그때 값이 새 이름으로
- * 남아 있으면 같은 결함이 반대 방향으로 난다.
- *
- * 멱등: 해당하는 행이 없으면 아무것도 하지 않는다. TypeORM 질의 빌더만 쓴다 — 드라이버마다 파라미터
- * 표기가 다르므로 raw SQL 을 쓰지 않는다.
- */
-const REFS = 'twin_references'
-const COLUMN = 'adapter_type'
-/**
- * 질의 빌더에는 **속성 이름**을 준다.
- *
- * 처음에 컬럼 이름(`adapter_type`)으로 썼더니 TypeORM 이 표 이름을 엔티티(`TwinReference`)로 풀고
- * 「그런 속성이 없다」로 거절했다 — 표 이름을 주더라도 매핑은 엔티티 기준이다. 컬럼 이름은 표가
- * 있는지 볼 때만 쓴다.
- */
-const PROPERTY = 'adapterType'
-const OLD = 'operato-mes'
-const NEW = 'operato-plant'
-
-async function rename(queryRunner: QueryRunner, from: string, to: string): Promise<void> {
-  /* 표가 아직 없는 배포(첫 기동)에서는 할 일이 없다. */
-  const table = await queryRunner.getTable(REFS)
-  if (!table?.columns.some(c => c.name === COLUMN)) return
-
-  /* 객체 형태로 준다 — 문자열 조건은 드라이버마다 식별자 인용이 달라 그대로 나간다. */
-  await queryRunner.manager
-    .createQueryBuilder()
-    .update(REFS)
-    .set({ [PROPERTY]: to })
-    .where({ [PROPERTY]: from })
-    .execute()
-}
-
-export class RenameOperatoMesAdapterType1786600000000 implements MigrationInterface {
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    await rename(queryRunner, OLD, NEW)
-  }
-
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    await rename(queryRunner, NEW, OLD)
-  }
-}

package/server/migrations/1786700000000-AddDispatchRetryColumns.ts

@@ -1,82 +0,0 @@
-/*
- * 조치 표에 **일꾼이 쓸 네 칸**을 더한다.
- *
- * ── 왜 표에 두나 ────────────────────────────────────────────────────────────
- * 물러섬을 메모리에 두면 재기동에 사라지고, 그러면 물러서던 것이 전부 즉시 재시도가 된다. 그리고
- * 일꾼이 여러 대가 되면 같은 답을 봐야 한다.
- *
- *   dispatch_note_next   저쪽 말 중 「다음에 할 일」 한 줄 — 원인은 dispatch_note
- *   retry                다시 해서 될 일인가 (again · after-fix · never)
- *   attempts             몇 번 넘겨 봤나 — 목록의 「몇 번 해 봤나」
- *   next_attempt_at      다음에 넘겨 볼 시각(ISO)
- *
- * ── 타입을 짐작하지 않는다 ──────────────────────────────────────────────────
- * 엔티티가 `@Column({ nullable: true })` 로 두면 그것이 어느 컬럼 타입이 되는지는 **드라이버마다
- * 다르다.** `'varchar'` 라고 적으면 sqlite·postgres·mysql 에서는 맞고 MSSQL·Oracle 에서 어긋난다.
- *
- * 그래서 같은 성질로 **이미 서 있는 형제 칸**의 타입을 읽어 그대로 쓴다 — 드라이버가 스스로 고른
- * 답이라 다섯 곳에서 다 맞는다. 형제가 없으면 짐작하지 않고 멈춘다.
- *
- *   글자 셋   dispatch_note 에서
- *   수 하나   effect_seen 에서
- *
- * plant 레인이 오늘 `equipmentClassIds` 마이그레이션에서 같은 방법을 썼다.
- *
- * ── 멱등 ────────────────────────────────────────────────────────────────────
- * 칸이 이미 있으면 아무것도 하지 않는다 — 개발 sqlite 는 엔티티 선언만으로 이미 만들어 둔다.
- * 표가 아직 없는 첫 기동에서도 할 일이 없다.
- */
-import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm'
-
-const TABLE = 'twin_command_records'
-
-/** 글자 칸의 형제 — 같은 성질(선택·자유 문자열)로 이미 서 있다. */
-const TEXT_SIBLING = 'dispatch_note'
-/** 수 칸의 형제 — 선택·정수. */
-const INT_SIBLING = 'effect_seen'
-
-const TEXT_COLUMNS = ['dispatch_note_next', 'retry', 'next_attempt_at'] as const
-const INT_COLUMNS = ['attempts'] as const
-
-export class AddDispatchRetryColumns1786700000000 implements MigrationInterface {
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    const table = await queryRunner.getTable(TABLE)
-    if (!table) return /* 첫 기동 — 엔티티가 만든다 */
-
-    const typeOf = (sibling: string): string | undefined => table.columns.find(c => c.name === sibling)?.type
-
-    const textType = typeOf(TEXT_SIBLING)
-    const intType = typeOf(INT_SIBLING)
-
-    /*
-     * 형제가 없으면 **멈춘다.** 짐작한 타입으로 칸을 세우면 어느 드라이버에서 어긋나는지 개발에서
-     * 안 잡히고, 그 배포에서만 난다.
-     */
-    if (!textType || !intType) {
-      throw new Error(
-        `${TABLE} 에서 형제 칸을 못 찾았습니다 — ${TEXT_SIBLING}(${textType ?? '없음'}) · ` +
-          `${INT_SIBLING}(${intType ?? '없음'}). 타입을 짐작하지 않고 멈춥니다`
-      )
-    }
-
-    for (const name of TEXT_COLUMNS) {
-      if (table.columns.some(c => c.name === name)) continue
-      await queryRunner.addColumn(TABLE, new TableColumn({ name, type: textType, isNullable: true }))
-    }
-
-    for (const name of INT_COLUMNS) {
-      if (table.columns.some(c => c.name === name)) continue
-      await queryRunner.addColumn(TABLE, new TableColumn({ name, type: intType, isNullable: true }))
-    }
-  }
-
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    const table = await queryRunner.getTable(TABLE)
-    if (!table) return
-
-    for (const name of [...TEXT_COLUMNS, ...INT_COLUMNS]) {
-      if (!table.columns.some(c => c.name === name)) continue
-      await queryRunner.dropColumn(TABLE, name)
-    }
-  }
-}

package/server/migrations/1786800000000-CreateTwinReferenceReconciliations.ts

@@ -1,39 +0,0 @@
-import { MigrationInterface, QueryRunner, Table, TableIndex } from 'typeorm'
-
-/* 번호 대사는 원본 범위를 실제로 읽은 뒤의 최신 상태를 재기동 뒤에도 보존한다. */
-const TABLE = 'twin_reference_reconciliations'
-
-export class CreateTwinReferenceReconciliations1786800000000 implements MigrationInterface {
-  public async up(queryRunner: QueryRunner): Promise<void> {
-    if (await queryRunner.hasTable(TABLE)) return
-    const dateType = queryRunner.connection.driver.mappedDataTypes.createDate as string
-    await queryRunner.createTable(new Table({
-      name: TABLE,
-      columns: [
-        { name: 'id', type: 'varchar', length: '36', isPrimary: true },
-        { name: 'domain_id', type: 'varchar', length: '36', isNullable: true },
-        { name: 'instance_id', type: 'varchar', isNullable: false },
-        { name: 'scope', type: 'varchar', isNullable: false },
-        { name: 'status', type: 'varchar', isNullable: false },
-        { name: 'source_first', type: 'int', isNullable: true },
-        { name: 'source_last', type: 'int', isNullable: true },
-        { name: 'cursor_seq', type: 'int', isNullable: true },
-        { name: 'first_seq_seen', type: 'int', isNullable: true },
-        { name: 'head_missing', type: 'int', isNullable: true },
-        { name: 'behind', type: 'int', isNullable: true },
-        { name: 'reason', type: 'varchar', isNullable: true },
-        { name: 'checked_at', type: dateType, isNullable: false },
-        { name: 'created_at', type: dateType, isNullable: true },
-        { name: 'updated_at', type: dateType, isNullable: true }
-      ]
-    }), true)
-    const table = await queryRunner.getTable(TABLE)
-    if (!table) return
-    await queryRunner.createIndex(table, new TableIndex({ name: 'uq_twin_reference_reconciliation_0', columnNames: ['domain_id', 'instance_id', 'scope'], isUnique: true }))
-    await queryRunner.createIndex(table, new TableIndex({ name: 'ix_twin_reference_reconciliation_0', columnNames: ['domain_id', 'instance_id', 'checked_at'] }))
-  }
-
-  public async down(queryRunner: QueryRunner): Promise<void> {
-    if (await queryRunner.hasTable(TABLE)) await queryRunner.dropTable(TABLE)
-  }
-}

package/server/migrations/index.ts

@@ -1,25 +0,0 @@
-/*
- * 마이그레이션 묶음 — 프레임워크 규약(`@things-factory/shell` · `auth-base` 와 같은 방식).
- * 파일마다 하나씩 export 하고 여기서 모아 `server/index.ts` 가 내보낸다.
- */
-import { RenameTwinInstanceBoardToModel1786000000000 } from './1786000000000-RenameTwinInstanceBoardToModel.js'
-import { PromoteEventActionAndSyncWarnings1786100000000 } from './1786100000000-PromoteEventActionAndSyncWarnings.js'
-import { CarryLiveFeedCursor1786200000000 } from './1786200000000-CarryLiveFeedCursor.js'
-import { IndexEventTypeByTime1786300000000 } from './1786300000000-IndexEventTypeByTime.js'
-import { IndexEventCreatedAt1786400000000 } from './1786400000000-IndexEventCreatedAt.js'
-import { CreateTwinSubjectEvents1786500000000 } from './1786500000000-CreateTwinSubjectEvents.js'
-import { AddDispatchRetryColumns1786700000000 } from './1786700000000-AddDispatchRetryColumns.js'
-import { CreateTwinReferenceReconciliations1786800000000 } from './1786800000000-CreateTwinReferenceReconciliations.js'
-import { RenameOperatoMesAdapterType1786600000000 } from './1786600000000-RenameOperatoMesAdapterType.js'
-
-export const migrations = [
-  RenameTwinInstanceBoardToModel1786000000000,
-  PromoteEventActionAndSyncWarnings1786100000000,
-  CarryLiveFeedCursor1786200000000,
-  IndexEventTypeByTime1786300000000,
-  IndexEventCreatedAt1786400000000,
-  CreateTwinSubjectEvents1786500000000,
-  RenameOperatoMesAdapterType1786600000000,
-  AddDispatchRetryColumns1786700000000,
-  CreateTwinReferenceReconciliations1786800000000
-]

package/server/routes.ts

@@ -1,75 +0,0 @@
-/*
- * 이 패키지가 여는 HTTP 자리 — 지금은 웹훅 하나다.
- *
- * ── 왜 여기인가 ─────────────────────────────────────────────────────────────
- * 커넥터는 주소를 만들 수 없다. 어댑터 계약에 주소를 등록하는 자리가 없고, 있어서도 안 된다 — 주소는
- * 앱의 것이고 커넥터마다 제각기 열면 인증도 제각기가 된다.
- *
- * 그래서 입구는 **하나**다. 어느 연결의 것인지는 주소의 이름으로 가려내고, 본문을 우리 어휘로 옮기는
- * 것은 그 연결의 커넥터가 한다(§`reference-hook`).
- *
- * ── 왜 도메인 공개 라우터인가 ───────────────────────────────────────────────
- * 밀어 주는 쪽은 사람이 아니다. 사람 인증(JWT)을 요구하면 연결된 시스템이 우리 토큰을 발급받아
- * 갱신하며 관리해야 하고, 대부분의 현장에서 그것 때문에 연동이 서지 않는다.
- *
- * 대신 **연결마다 비밀값**을 두고 그것으로 확인한다. 비밀값을 선언하지 않은 연결은 훅을 받지 않는다 —
- * 인증 없는 입구를 열어 두는 것보다 훅을 못 쓰는 것이 낫다.
- */
-import { liveIngest } from './service/reference/live-ingest.js'
-import { requestFill } from './service/reference/fill-loop.js'
-import { handleHook } from './service/reference/reference-hook.js'
-import { deliverAttention } from './service/reference/attention-lane.js'
-import { databaseStore } from './service/reference/hook-store.js'
-
-process.on('bootstrap-module-domain-public-route' as any, (_app: any, router: any) => {
-  /*
-   * 주소에 트윈까지 적는다 — 어느 트윈에 넣을지 짐작하지 않는다.
-   *
-   * 한 연결이 여러 사이트를 만들면 트윈도 여럿이다. 본문을 보고 고르게 하면 그 판단이 커넥터마다
-   * 달라지고, 틀리면 다른 공장의 사실이 이 공장에 들어간다. 주소가 말하게 하면 그 일이 없다.
-   */
-  router.post('/twin/hook/:source/:instanceId', async (ctx: any) => {
-    const domain = ctx.state?.domain
-    if (!domain) {
-      ctx.status = 400
-      ctx.body = { ok: false, error: 'no domain context' }
-      return
-    }
-    const outcome = await handleHook({
-      domainId: domain.id,
-      source: String(ctx.params.source ?? ''),
-      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` 한 줄뿐이다.
-       */
-      /*
-       * 유입 몸통은 `live-ingest.ts` 한 곳에 있다 — backfill 이 같은 것을 쓴다. 여기에 두면 두 길이
-       * 서로 다른 규칙으로 받게 되고, 한쪽만 수정되는 날이 온다.
-       */
-      ingest: (instanceId, records, lane) => lane === 'FACTS'
-        ? liveIngest(domain.id, instanceId, records, 'hook')
-        : deliverAttention({ domainId: domain.id, source: String(ctx.params.source ?? ''), instanceId, records }),
-      /*
-       * 구멍을 본 그 자리에서 바로 받는다 — 번호가 비었다는 것을 아는 가장 이른 순간이다.
-       * 기다리지 않는다(§`requestFill`): 훅의 응답이 늦으면 보내는 쪽이 되풀이한다.
-       */
-      onGap: scope => requestFill(domain.id, String(ctx.params.instanceId ?? ''), scope)
-    })
-    ctx.status = outcome.status
-    ctx.body = outcome.body
-  })
-})
-
-/* 나머지 셋은 이 패키지가 쓰지 않는다 — 자리는 남겨 둔다(다른 모듈이 같은 신호를 기다린다). */
-process.on('bootstrap-module-global-public-route' as any, (_app: any, _router: any) => {})
-process.on('bootstrap-module-global-private-route' as any, (_app: any, _router: any) => {})
-process.on('bootstrap-module-domain-private-route' as any, (_app: any, _router: any) => {})

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

@@ -1,131 +0,0 @@
-/*
- * **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: {
-    /*
-     * The tenant the command belongs to. Required: the advisor's tools read the twin through it, and without it
-     * every tool answers "no domain context" while the opinion is still written from the prompt alone
-     * (2026-09-17 — the twin app passed nothing because this input had no place for it).
-     */
-    domainId: string
-    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: {
-  domainId: string
-  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({ domainId: args.domainId, 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

@@ -1,97 +0,0 @@
-/*
- * **조치가 어떻게 됐나** — 승인한 사람에게 돌려줄 사실 한 묶음.
- *
- * ── 왜 판정을 커널이 하나 (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
-  }
-}