@things-factory/headless-twin 10.1.277 → 10.1.279

package/server/service/reference/template-registry.ts

@@ -1,85 +0,0 @@
-/*
- * 트윈 템플릿(아키타입) 레지스트리 — 파라미터화된 합성 레퍼런스 마스터 빌더.
- * 레퍼런스(reference-registry)가 "고정 마스터"라면, 템플릿은 "노브로 파라미터화된 마스터 빌더".
- * 둘 다 같은 인제스트 경로(ingestMaster)로 흐른다 — 원천이 고정이냐 합성이냐만 다르다(board-authoring §10).
- * 앱(operato-twin)이 bootstrap 에서 자기 아키타입을 registerTemplate 한다. 표현(map/image/model) 무관.
- */
-import type { DomainSystem } from '@operato/ops-contract'
-
-import type { ReferenceMaster } from './reference-master.js'
-
-/** 사용자 노출 파라미터(노브) 정의 — 클라이언트가 이 스키마로 폼을 렌더한다. */
-export interface KnobDef {
-  key: string
-  /** 'geo' = 위경도 지점(지도에서 클릭 선택). 값은 { lat, lon }. 사용자가 좌표를 몰라도 지도로 지정. */
-  label: string
-  /**
-   * 'siteEquipment' = **이 현장에 이미 있는 설비들**(`{id, kind}`). 값이 비어 있으면 만들 때 한 번
-   * 해석해서 채우고, 채운 결과를 노브 값으로 **남긴다**(`origin.params`). 그래야 나중에 다시 지어도
-   * 같은 트윈이 나온다 — 그때그때 현장을 다시 읽으면 사이에 설비가 늘고 준 만큼 다른 트윈이 된다.
-   *
-   * 종류를 함께 싣는 이유: 무엇을 받아들일지는 **템플릿이 종류로 판단**한다(이름으로 짐작하지 않는다).
-   */
-  type: 'number' | 'text' | 'select' | 'geo' | 'siteEquipment'
-  default: any
-  min?: number
-  max?: number
-  options?: { value: string; label: string }[]
-  help?: string
-}
-
-/**
- * 템플릿 상세(설명 페이지용, 선택) — "이 템플릿이 무엇을 모델링하나"를 구조적으로 보여줘 확신을 준다.
- * 순수 표시용 데이터(빌드 로직과 무관). 클라이언트가 이 스키마로 상세 뷰를 렌더한다.
- */
-export interface TemplateDetail {
-  /** 한 줄 요약(누구를 위한/무엇). */
-  summary?: string
-  standards?: string[]
-  /** 밸류체인 국면(반입·보관·변환·반출 등). */
-  phases?: { key: string; label: string; system?: string; note?: string }[]
-  /** 공정 라우트(오퍼레이션 시퀀스). */
-  route?: { op: string; label?: string; resource?: string; intent?: string; bizStep?: string }[]
-  locationTypes?: { key: string; label?: string; standardClass?: string; capabilities?: string[] }[]
-  resourceTypes?: { key: string; label?: string; standardClass?: string; capabilities?: string[] }[]
-  /** BOM/레시피 요약. */
-  recipe?: {
-    inputs: { material: string; qty: number; key?: string }[]
-    outputs: { material: string; qty: number; key?: string }[]
-    /** 완성 라우트 이름(공정 라우트 참조). */
-    route?: string
-  }
-  /**
-   * 표준 정합 매핑 — 개념이 **어느 표준의 무엇에 대응하나.**
-   *
-   * 표준 칸이 EPCIS·ISA-95 둘로 굳어 있었다. 에너지 템플릿은 그 둘이 앵커가 아니라 적을 자리가 없었다 —
-   * 커널의 `StandardClass` 도 같은 이유로 열었다(`iso50001`·`iec61850`). 대응할 이름이 없으면 **비운다**.
-   */
-  standardsMap?: { concept: string; epcis?: string; isa95?: string; iso50001?: string; iec61850?: string }[]
-  /** "이 템플릿이 맞나?" 판단 도움 항목. */
-  fits?: string[]
-}
-
-export interface TwinTemplate {
-  id: string
-  label: string
-  /** 커널 카탈로그가 정본 — 종류가 늘면 여기 손댈 것이 없다(`DomainSystem`). */
-  system: DomainSystem
-  description?: string
-  /** 상세 설명(선택) — 설명 페이지/패널이 렌더. */
-  detail?: TemplateDetail
-  knobs: KnobDef[]
-  /** 노브 값 → 합성 마스터(+옵션 시나리오). scenario 는 runtime.scenario.load 로 전달되는 불투명 값. */
-  build(params: Record<string, any>): { master: ReferenceMaster; scenario?: any }
-}
-
-const templates = new Map<string, TwinTemplate>()
-export function registerTemplate(tpl: TwinTemplate): void {
-  templates.set(tpl.id, tpl)
-}
-export function listTemplates(): TwinTemplate[] {
-  return [...templates.values()]
-}
-export function getTemplate(id: string): TwinTemplate | undefined {
-  return templates.get(id)
-}

package/server/service/reference/twin-reference-reconciliation.ts

@@ -1,27 +0,0 @@
-import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId, UpdateDateColumn } from 'typeorm'
-import { Field, ID, Int, ObjectType } from 'type-graphql'
-import { Domain } from '@things-factory/shell'
-
-/* 한 연결·Twin·단위의 최신 번호 대사 상태. 과거 추이는 ingest window가, 현재 조치 판단은 이 표가 답한다. */
-@Entity()
-@Index('uq_twin_reference_reconciliation_0', (e: TwinReferenceReconciliation) => [e.domain, e.instanceId, e.scope], { unique: true })
-@Index('ix_twin_reference_reconciliation_0', (e: TwinReferenceReconciliation) => [e.domain, e.instanceId, e.checkedAt], { unique: false })
-@ObjectType({ description: 'Latest durable sequence reconciliation for one connected source scope. It reports only what numbered source ranges can prove; it never substitutes replay-prone ingest-window counts for source facts.' })
-export class TwinReferenceReconciliation {
-  @PrimaryGeneratedColumn('uuid') @Field(type => ID) readonly id: string
-  @ManyToOne(type => Domain) @Field(type => Domain, { nullable: true }) domain?: Domain
-  @RelationId((e: TwinReferenceReconciliation) => e.domain) domainId?: string
-  @Column() @Field() instanceId: string
-  @Column() @Field() scope: string
-  @Column() @Field() status: 'aligned' | 'gap' | 'unknown'
-  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) sourceFirst?: number
-  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) sourceLast?: number
-  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) cursorSeq?: number
-  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) firstSeqSeen?: number
-  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) headMissing?: number
-  @Column({ type: 'int', nullable: true }) @Field(type => Int, { nullable: true }) behind?: number
-  @Column({ nullable: true }) @Field({ nullable: true }) reason?: string
-  @Column() @Field() checkedAt: Date
-  @CreateDateColumn() createdAt?: Date
-  @UpdateDateColumn() updatedAt?: Date
-}

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

@@ -1,190 +0,0 @@
-import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
-import { ObjectType, Field, ID, Int } from 'type-graphql'
-
-import type { RefusalCode, RefusalParams } from '@operato/ops-contract'
-
-import { Domain, ScalarObject, encryptedJsonColumn } from '@things-factory/shell'
-
-/** 조치 검증 상태 — 「아직 안 해 봤다」는 실패가 아니라 그 자체로 하나의 사실이다. */
-export type ActuationState = 'unverified' | 'verified' | 'failed'
-
-/** 마지막 거절 — 언어 중립 코드와 그 값들. 사람 문장은 담지 않는다. */
-export interface ActuationFailure {
-  code: RefusalCode
-  /** 거절된 시각 (ISO 8601). */
-  at: string
-  params?: RefusalParams
-}
-
-/*
- * TwinReference — 테넌트 스코프의 외부 소스 시스템 연결(실 또는 가상). 트윈 인스턴스가 인제스트되는 원천(Face2, ADR-0018).
- * 전역 인메모리 레퍼런스 레지스트리를 대체하는 영속·도메인별·어댑터 기반 엔티티.
- * inbound 전용(구조·상태). 아웃바운드 액추에이션은 command-routing(ActuationAdapter) 소유.
- * mappingSpec/scopeSpec 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통).
- * connectionConfig 는 자격 증명을 담으므로 암호화되는 텍스트 칸이다(칸 주석 참조).
- * 설계 SoT: operato-twin/design/plans/reference-management.md.
- * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)
- */
-@Entity()
-@Index('ix_twin_reference_0', (e: TwinReference) => [e.domain, e.source], { unique: true })
-@ObjectType({ description: 'A tenant-scoped connection to an external source system — the origin for ingesting twin instances (Face2).' })
-export class TwinReference {
-  @PrimaryGeneratedColumn('uuid')
-  @Field(type => ID, { description: 'Unique identifier of the reference record.' })
-  readonly id: string
-
-  @ManyToOne(type => Domain)
-  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
-  domain?: Domain
-
-  @RelationId((e: TwinReference) => e.domain)
-  domainId?: string
-
-  @Column()
-  @Field({ description: 'Reference source id (unique within a domain).' })
-  source: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Domain kernel system: wms | yms | mes.' })
-  system?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Human-readable site/system name.' })
-  siteName?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Optional description.' })
-  description?: string
-
-  @Column()
-  @Field({ description: "Adapter type registry key (e.g. 'virtual' | 'rest' | 'db' | 'epcis')." })
-  adapterType: string
-
-  /**
-   * 이 연결에 필요한 값 — **자격 증명이 여기 들어온다. 그래서 저장될 때 암호화된다.**
-   *
-   * ── 왜 표에 두나 (2026-09-09) ─────────────────────────────────────────────
-   * 비밀값은 환경에 두고 이름으로 고르는 것이 원칙이다(§`webhookSecretCandidates`). 그 원칙은
-   * **설치본마다 하나인 키**에 맞는다 — 배포할 때 넣으면 된다.
-   *
-   * 트윈의 연결은 그 모양이 아니다. **사람이 화면에서 연결을 만든다.** 새 공장을 붙이려고 재배포할
-   * 수는 없으므로, 연결마다 다른 이 값은 표에 있어야 한다. 그 자리에서 원칙이 갈린다:
-   *
-   *     설치본마다 하나인 키   환경변수. 이름이 어느 상대 것인지 말한다
-   *     연결마다 다른 값       표. 대신 저장될 때 암호화한다
-   *
-   * ── 무엇을 지키고 무엇을 못 지키나 ────────────────────────────────────────
-   * 저장된 것을 지킨다 — DB 파일 · 백업 · 복제본. 2026-09-09 에 이 칸에서 `hookSecret` 과 접속
-   * 토큰을 명령 두 개로 읽었다.
-   *
-   * **프로세스를 돌릴 수 있는 사람에게서는 못 지킨다** — 그 사람은 키를 갖고 있다. 그리고 값이
-   * 화면으로 나가는 것도 이 칸이 막지 않는다: 내보내는 쪽이 어댑터 스키마의 `secret: true` 를 보고
-   * 가린다(§`reference-resolver` 의 상세 조회). **두 가지가 갈려 있으므로 한쪽만 하면 반쪽이다.**
-   *
-   * 기존 평문 행은 안 깨진다 — 변환기가 암호문 모양이 아닌 값을 알아보고 파싱하며 경고를 남기고,
-   * 다시 저장될 때 암호화된다.
-   */
-  @Column({ nullable: true, ...encryptedJsonColumn() })
-  @Field(type => ScalarObject, { nullable: true, description: 'Adapter-specific connection config (endpoint, credentials, params). Encrypted at rest; secret-declared fields are masked on the way out.' })
-  connectionConfig?: any
-
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'Declarative legacy→canonical mapping rules (kernel face2-adapter AdapterRule[]).' })
-  mappingSpec?: any
-
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: '1:N fan-out scope (discovered sites). Multiple sites → N instances.' })
-  scopeSpec?: any
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Lifecycle status: draft | connected | error.' })
-  status?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Last successful master sync time (ISO 8601 string; portable across DB drivers).' })
-  lastSyncedAt?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Last connection/sync error message, if any.' })
-  lastError?: string
-
-  /**
-   * **조치를 이 주소로 실제로 넘겨 봤나** (ADR-0046 ②).
-   *
-   * ── 왜 세 값인가 ───────────────────────────────────────────────────────────
-   * 설정이 맞는 것과 저쪽이 받는 것은 다르다. 주소도 비밀값도 다 적혀 있는데 저쪽 프로세스가 그 값을
-   * 잃은 일이 실제로 있었다(§`actuationReadiness`). 그것은 **한 번 넘겨 봐야** 알 수 있고, 그래서
-   * 「아직 안 해 봤다」와 「해 봤고 됐다」와 「해 봤고 안 됐다」가 다른 사실이다.
-   *
-   *   unverified  아직 왕복이 없다 — 실패가 아니다. 새 연결과 설정이 바뀐 연결이 여기 선다
-   *   verified    `actuate` 가 받아들여졌다. 그 시각이 `actuationVerifiedAt`
-   *   failed      거절됐다. 사유는 `actuationFailure` 에 **코드로**
-   *
-   * `unverified` 를 `failed` 로 접지 않는다 — 안 해 본 것을 실패로 그리면 사람이 고칠 것을 찾으러
-   * 가고, 고칠 것이 없다.
-   */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: "Whether an actuation has actually reached this peer: 'unverified' | 'verified' | 'failed'. Null means the same as unverified; a connection that has never been tried is not a failed one." })
-  actuationState?: ActuationState
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'When an actuation was last accepted by the peer (ISO 8601 string; portable across DB drivers). Null while unverified.' })
-  actuationVerifiedAt?: string
-
-  /**
-   * 마지막 거절 — **코드와 값만 저장한다. 문장은 저장하지 않는다.**
-   *
-   * `lastError` 가 사람 문장을 저장해 두고 화면이 그것을 그대로 뿌렸다. 그러면 번역이 안 되고, 무엇이
-   * 몇 번 났는지 세지도 못하고, 커넥터가 문장을 고치는 날 옛 행과 새 행이 서로 다른 말을 한다.
-   * 코드는 `CommandAck.errorCode` 와 같은 낱말이다(ADR-0042 ③) — 표현층이 문장을 만든다.
-   */
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'Why the last actuation was refused: { code, at, params? }. Language-neutral codes only — the presentation layer builds the sentence. Null when the last attempt was accepted or none was made.' })
-  actuationFailure?: ActuationFailure
-
-  /**
-   * 마지막 동기에서 **못 옮긴 값의 수**. `null` = 세지 않았다(0 과 다르다).
-   *
-   * 세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 성공이라 답하면서 아무 일도 하지 않는다. 그 사실을 사후에 물을 수
-   * 있어야 단계 판정이 「구조는 됐다」를 말할 수 있다 — 없는 동안 판정은 늘 `unmeasured` 였다.
-   * 기본값을 두지 않는다: 0 을 기본으로 깔면 「경고 없었다」와 「세지 않았다」가 같아진다.
-   */
-  @Column({ type: 'int', nullable: true })
-  @Field(type => Int, { nullable: true, description: 'Number of values the last sync could not carry over (mapping fallbacks). Null means they were not counted at all, which is different from zero.' })
-  lastWarningCount?: number
-
-  /**
-   * **어디까지 읽었나** — 라이브 피드의 읽기 커서(§`LiveFeedContinuity`).
-   *
-   * ── 왜 저장하나 (2026-08-23 실측) ──────────────────────────────────────────
-   * 어댑터가 붙을 때마다 `Date.now() − 되돌아볼 날수` 로 창을 새로 만들고 있었다. 그래서 **재기동마다
-   * 미러의 과거가 잘렸다** — 작업 2,855 → 2,820(8시간 흐른 만큼). 미러가 아는 것이 「원본의 사실」이
-   * 아니라 「창의 함수」였고, 그 사실을 아무도 말하지 않았다.
-   *
-   * 커널이 그 갈림을 이미 적어 두었다(§`hydrateContinuity`): 「원천이 애초에 다시 말해 주지 않는 축」은
-   * 재기동 연속성으로 이어받는다. 「우리가 어디까지 읽었나」가 정확히 그 성질이므로 **어댑터의 사물함이
-   * 아니라 이 층**에 있다 — 원본이 늘 때마다 저장 기제가 늘고 그중 하나가 알리지 않고 다르게 동작하지 않게.
-   *
-   * ── 왜 캐시가 아니라 표인가 ────────────────────────────────────────────────
-   * 만료되면 창이 다시 미끄러지고, 그 손실은 오류 없이 들어온 것이 없다. 스냅샷 체크포인트와 성질이 다르다
-   * (그쪽은 잃어도 원천이 정정해 준다 — 이 값은 **잃으면 원천에 묻지 않게 된다**).
-   *
-   * 모양은 `{ streams: { [흐름]: { since?, seen[] } }, firstAttachedAt? }` 다. **흐름 이름은 어댑터가
-   * 정한다** — 원본마다 흐름 수와 뜻이 다르므로 이 층은 열쇠로만 다룬다. `simple-json` 이라 드라이버
-   * 다섯을 그대로 지난다.
-   *
-   * `firstAttachedAt` 은 「언제부터 아는가」다. 커널은 상한만 안다(`nowTime` = 마지막으로 들은 시각).
-   * 둘이 함께 「이 트윈이 아는 구간」이고, 화면이 수를 보일 때 그 구간을 말해야 한다.
-   */
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'Live feed read cursor carried across restarts, keyed by adapter-defined stream. Null means the feed has never attached, and the next attach decides its first window.' })
-  liveCursor?: any
-
-  @CreateDateColumn()
-  @Field({ nullable: true, description: 'Timestamp when the reference was first created.' })
-  createdAt?: Date
-
-  @UpdateDateColumn()
-  @Field({ nullable: true, description: 'Timestamp when the reference row was last updated.' })
-  updatedAt?: Date
-}

package/server/service/twin-attention/index.ts

@@ -1,3 +0,0 @@
-import { TwinAttentionQuery } from './twin-attention-query.js'
-
-export const resolvers = [TwinAttentionQuery]

package/server/service/twin-attention/twin-attention-query.ts

@@ -1,70 +0,0 @@
-import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
-
-import { ScalarObject } from '@things-factory/shell'
-
-import { TwinEngine } from '../../engine/index.js'
-import { digestAttentions } from '../../engine/attention-digest.js'
-
-/*
- * 주목 신호(Attention) 질의 — 현재 스냅샷의 요약된 "봐야 할 것".
- * 커널 computeAttentions() 파생: severity(ISA-18.2/IEC 62682) · state(OPC UA A&C) ·
- * anchor(locationId/moverId/orderId = 공간 위치) · suggestedAction(조치 제안). kind 는 도메인 소유(무방언).
- * full StateSnapshot 대신 이 경량 목록을 AI read 도구·insight UI 가 소싱(대용량 덤프 회피).
- * (실시간 스트림은 twinState subscription 이 attentions 를 포함. 이건 one-shot '질의' 표면.)
- */
-@Resolver()
-export class TwinAttentionQuery {
-  @Query(returns => [ScalarObject], {
-    description: 'Active attention signals (things to look at) derived from the current twin snapshot — severity (ISA-18.2), lifecycle state (OPC UA A&C), space anchor, and suggested action.'
-  })
-  async twinAttentions(
-    @Ctx() context: ResolverContext,
-    @Arg('instanceId', { nullable: true }) instanceId?: string,
-    /*
-     * **공간으로 물으면 그 현장의 모든 렌즈에서 모아 답한다** — 한 현실을 WMS·MES·YMS 가 함께 비추므로
-     * "이 현장에서 봐야 할 것" 은 렌즈 하나로 답할 수 없다. 예전에는 화면이 인스턴스마다 물어 손으로
-     * 합쳤고, 그러면 정렬 규칙이 화면마다 갈린다.
-     *
-     * 경고는 **합집합이 그대로 뜻이 있는 유일한 렌즈**다. 예측은 합칠 수 없다(P50 두 개를 더할 수 없다) —
-     * 그래서 예측은 여전히 인스턴스별로 답하고 화면이 나란히 놓는다.
-     */
-    @Arg('spaceId', { nullable: true }) spaceId?: string
-    /*
-     * ── 자르는 인자는 여기 없다 (2026-09-19, 수석 아키텍트 판정) ──────────────
-     *
-     * `limit` 이 있었다. 자르면서 **몇 건을 잘랐는지는 답에 싣지 못했다** — 답이 맨 목록이라 실을
-     * 자리가 없었기 때문이다. 자를 수 있는 문이 잘린 수를 못 말하면, 스무 건만 받은 화면은 그것이
-     * 전부인지 이백 중 스무 건인지 구별할 수 없다.
-     *
-     * 자르려는 소비자는 `twinAttentionDigest` 를 쓴다 — 그 문은 `attentionTotal` 을 함께 답하고,
-     * 자리별 색을 **전량을 근거로** 계산한다. 이 문은 자르지 않는다.
-     */
-  ): Promise<any[]> {
-    if (spaceId) return (await TwinEngine.attentionsOfSpace(context.state.domain.id, spaceId)).attentions
-    if (!instanceId || !TwinEngine.owns(context.state.domain.id, instanceId)) return [] // 테넌트 격리
-    // 라이브 커널 스냅샷(fresh) 우선 — snapshot()=resync() 는 캐시라 커맨드 델타 지연(recover 와 동일 원천 사용).
-    const kernel = TwinEngine.kernel(context.state.domain.id, instanceId)
-    const snap = kernel?.getSnapshot?.() ?? TwinEngine.snapshot(context.state.domain.id, instanceId)
-    return snap?.attentions ?? []
-  }
-
-  /**
-   * 잘랐다면 **몇 건을 잘랐는지**와 자리 색 요약까지 — 목록만 주면 화면이 "N건 더" 를 말할 수 없다.
-   * 자리별 최고 심각도는 **전량을 근거로** 계산한다(상위 N 으로 줄이면 20위 밖 신호를 가진 자리가 색을 잃는다).
-   */
-  @Query(returns => ScalarObject, {
-    description: 'Attention signals for a space (all its lenses) or one twin, with the total count and the per-location highest severity folded from all of them.'
-  })
-  async twinAttentionDigest(
-    @Ctx() context: ResolverContext,
-    @Arg('spaceId', { nullable: true }) spaceId?: string,
-    @Arg('instanceId', { nullable: true }) instanceId?: string,
-    @Arg('limit', type => Int, { nullable: true }) limit?: number
-  ): Promise<any> {
-    if (spaceId) return TwinEngine.attentionsOfSpace(context.state.domain.id, spaceId, limit ?? undefined)
-    if (!instanceId || !TwinEngine.owns(context.state.domain.id, instanceId)) return { attentions: [], attentionTotal: 0, severityByLocation: {} }
-    const kernel = TwinEngine.kernel(context.state.domain.id, instanceId)
-    const snap = kernel?.getSnapshot?.() ?? TwinEngine.snapshot(context.state.domain.id, instanceId)
-    return digestAttentions((snap?.attentions ?? []).map((a: any) => ({ ...a, instanceId })), limit ?? undefined)
-  }
-}

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

@@ -1,114 +0,0 @@
-/*
- * 커맨드 감사 기록 만들기 (순수) — **누가 무엇을 허락했고, 그래서 어떻게 됐나.**
- *
- * 승인 게이트가 앞을 막고, 이 기록이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를 증명할 수 있다.
- *
- * 무엇을 믿는가가 이 기록의 전부다:
- *  · **신원·시각은 서버가 준다.** 클라이언트가 말한 신원을 그대로 적으면 위조가 자유로워 아무것도
- *    증명하지 못한다. 세션이 아는 사용자와 서버 시각만 쓴다.
- *  · **의도는 클라이언트가 준다** — 출처(origin)·근거(reason). 서버가 알 수 없는 정보이고,
- *    위조되더라도 신원 증명을 훼손하지 않는다.
- */
-
-export type CommandOrigin = 'user' | 'ai' | 'automation' | 'unknown'
-
-export type CommandAuditInput = {
-  /** 클라이언트가 실어 보낸 커맨드(신뢰하지 않는 부분을 포함한 원본). */
-  command: any
-  /** 커널 판정. */
-  ack: { accepted?: boolean; errorCode?: string; error?: string }
-  /**
-   * **원본(어댑터)이 준 답** — 허락과 일어남 사이에 끼어 있는 것을 같은 기록에 닫는다 (ADR-0029 §1 결정 C).
-   *
-   * ── 왜 이 칸이 필요한가 ──────────────────────────────────────────────────
-   * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다 — 어댑터가 오류 없이 실패하면 원장에는 승인만
-   * 남는다. 그래서 어댑터의 답을 **같은 행**에 되적는다.
-   *
-   * 셋을 구별한다:
-   *  · 없음(`undefined`) — **원본에 묻지 않았다**(커널이 받은 명령이다). 「모른다」와 다르다.
-   *  · `{ answered: false }` — 물었는데 **답을 못 받았다** → `unknown` 으로 남긴다. 성공으로 적지 않는다.
-   *  · `{ answered: true, ok, code? }` — 원본이 답했다(적용·거절 모두 사실이다).
-   */
-  source?: { answered: boolean; ok?: boolean; code?: string }
-  /** 세션이 아는 사용자 — **서버만 채운다.** */
-  actor?: { id?: string; email?: string; name?: string }
-  /** 서버 시각. 호출부가 주입해 테스트가 시간을 고정할 수 있게 한다. */
-  at: Date
-}
-
-/** `TwinAuditEvent` 에 그대로 넣을 수 있는 모양(엔티티를 몰라도 되게 순수하게 둔다). */
-export type CommandAuditRow = {
-  eventTime: Date
-  commandId?: string
-  commandType?: string
-  origin: CommandOrigin
-  reason?: string
-  actorId?: string
-  actorEmail?: string
-  actorName?: string
-  accepted: boolean
-  errorCode?: string
-  /**
-   * 원본이 그래서 어떻게 했나 — `applied` · `refused` · `unknown`(물었지만 답이 없다).
-   * **없으면 묻지 않은 것이다**(커널이 받은 명령). 0 이나 성공으로 채우지 않는다.
-   */
-  sourceOutcome?: 'applied' | 'refused' | 'unknown'
-  /** 원본이 준 사유 코드 — 있으면 그대로. 우리가 지어내지 않는다. */
-  sourceCode?: string
-  args?: any
-  argsTruncated: boolean
-}
-
-/** 신뢰할 수 있는 출처 표기로 정규화 — 모르는 값은 지어내지 않고 'unknown' 으로 둔다. */
-export function normalizeOrigin(v: unknown): CommandOrigin {
-  return v === 'user' || v === 'ai' || v === 'automation' ? v : 'unknown'
-}
-
-/** args 직렬화 상한(문자). 넘으면 자르되 잘랐다고 표시한다. */
-const ARGS_MAX = 4000
-
-export function buildCommandAudit(input: CommandAuditInput): CommandAuditRow {
-  const { command, ack, actor, at, source } = input
-  const argsText = safeJson(command?.args)
-  const truncated = argsText !== null && argsText.length > ARGS_MAX
-  return {
-    eventTime: at,
-    commandId: str(command?.commandId),
-    commandType: str(command?.type),
-    origin: normalizeOrigin(command?.origin),
-    reason: str(command?.reason),
-    /* 원본의 답 — 묻지 않았으면 칸을 만들지 않는다(모름과 구별한다). */
-    ...(source ? { sourceOutcome: sourceOutcomeOf(source), ...(source.code ? { sourceCode: source.code } : {}) } : {}),
-    /* 신원 — 세션 값만. 커맨드에 실려 온 신원 주장은 쳐다보지 않는다. */
-    actorId: str(actor?.id),
-    actorEmail: str(actor?.email),
-    actorName: str(actor?.name),
-    /* 결과 — 승인했는데 커널이 거절한 것도 감사 대상이다(무엇을 시도했는지가 남아야 한다). */
-    accepted: !!ack?.accepted,
-    errorCode: str(ack?.errorCode),
-    /* 인자는 원형 그대로. 너무 크면 잘린 문자열로 두되 잘랐다고 말한다. */
-    args: truncated ? argsText!.slice(0, ARGS_MAX) : command?.args ?? undefined,
-    argsTruncated: truncated
-  }
-}
-
-const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined)
-
-function safeJson(v: unknown): string | null {
-  try {
-    return v === undefined ? null : JSON.stringify(v)
-  } catch {
-    return null /* 순환 참조 등 — 못 재면 자르지 않는다(원본을 그대로 둔다) */
-  }
-}
-
-/**
- * 원본의 답을 세 값으로 — **답이 없으면 `unknown`**(성공으로 적지 않는다).
- *
- * 이 함수가 있는 이유: 「물었지만 답이 없다」를 실패로도 성공으로도 적을 수 없다. 실패로 적으면 일어난 일을
- * 없던 일로 만들고, 성공으로 적으면 없던 일을 일어난 일로 만든다. 셋째 값이 사실이다.
- */
-export function sourceOutcomeOf(source: { answered: boolean; ok?: boolean }): 'applied' | 'refused' | 'unknown' {
-  if (!source.answered || typeof source.ok !== 'boolean') return 'unknown'
-  return source.ok ? 'applied' : 'refused'
-}

package/server/service/twin-audit/index.ts

@@ -1,5 +0,0 @@
-import { TwinAuditEvent } from './twin-audit-event.js'
-import { TwinAuditQuery } from './twin-audit-query.js'
-
-export const entities = [TwinAuditEvent]
-export const resolvers = [TwinAuditQuery]

package/server/service/twin-audit/twin-audit-event.ts

@@ -1,158 +0,0 @@
-import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'
-import { ObjectType, Field, ID } from 'type-graphql'
-
-import { Domain, ScalarObject } from '@things-factory/shell'
-import { config } from '@things-factory/env'
-
-/*
- * 긴 글의 컬럼 타입은 **드라이버마다 이름이 다르다** — 이 레포의 정본 관행대로 여기서 고른다
- * (board-service 의 `Board.model` 과 같은 방식). `text` 를 그대로 적었더니 Oracle 이 모르는 이름이었다.
- */
-const DATABASE_TYPE = config.get('ormconfig', {}).type
-
-/*
- * TwinAuditEvent — **사람이 무엇을 허락했는가.**
- *
- * ── 왜 저널(TwinEvent)이 아닌가 ───────────────────────────────────────────────
- * 처음에는 저널에 함께 넣었다. "감사는 원장에서 하니까" 라는 이유였는데, 그건 **화면의 편의**였고
- * 저장 구조를 정할 근거가 못 됐다. 넣자마자 예외가 넷 생겼다 — 리플레이에서 빼고, 백필에서 빼고,
- * 원장 거래 분류에서 빼고, 원장 렌더에서 갈랐다. **예외가 넷이면 설계가 "여기 아니다" 라고 말하는 것이다.**
- *
- * 갈라 두면 예외가 0 이고, 오히려 얻는다:
- *  · 행위자가 **컬럼**이 된다 — "누가 승인한 것 전부" 는 감사의 기본 질문인데 payload 안에서는 못 찾았다
- *  · revision 이 없다. 저널에서는 그 칸을 비워 "상태가 아님" 을 뜻하게 썼는데, 없음을 종류 표시로
- *    쓰는 것이 여러 번 문제를 냈다(백필의 `bizStep IS NULL = 옛 행` 전제가 이것 때문에 깨졌다)
- *  · bizStep 오염이 없다 — 저널의 키 추출기는 값이 없으면 이벤트 타입으로 대체하므로,
- *    감사 행을 태우면 CBV 표준 어휘 컬럼에 `governance.command` 가 박힌다
- *
- * ── 무엇을 믿는가 ────────────────────────────────────────────────────────────
- * **신원·시각은 서버가 각인한다.** 클라이언트가 말한 신원을 그대로 적으면 위조가 자유로워 그 기록은
- * 아무것도 증명하지 못한다. 세션이 아는 사용자와 서버 시각만 신뢰한다.
- * 클라이언트에서 받는 것은 **의도**뿐이다 — 어디서 시작됐나(origin), 왜 하나(reason).
- */
-@Entity()
-/* 목록 기본 정렬 — 최근 것부터. 감사는 "요즘 무슨 일이 있었나" 로 시작한다. */
-@Index('ix_twin_audit_0', (e: TwinAuditEvent) => [e.domain, e.instanceId, e.eventTime], { unique: false })
-/* 행위자로 찾기 — 저널에 있을 때는 불가능했던 질문("김현장이 승인한 것 전부"). */
-@Index('ix_twin_audit_1', (e: TwinAuditEvent) => [e.domain, e.actorEmail, e.eventTime], { unique: false })
-@ObjectType({ description: 'Audit record of a twin command: who approved what, and what the kernel answered.' })
-export class TwinAuditEvent {
-  @PrimaryGeneratedColumn('uuid')
-  @Field(type => ID, { description: 'Unique identifier of the audit record.' })
-  readonly id: string
-
-  @ManyToOne(type => Domain)
-  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
-  domain?: Domain
-
-  @RelationId((e: TwinAuditEvent) => e.domain)
-  domainId?: string
-
-  @Column()
-  @Field({ description: 'Twin runtime instance the command was aimed at.' })
-  instanceId: string
-
-  /*
-   * 서버 시각. 클라이언트 시계를 믿지 않는다 — 기록의 시간축이 단말 설정에 좌우되면 안 된다.
-   *
-   * **타입 이름은 적지 않는다** (2026-08-19 Postgres 부팅 실패로 고침).
-   * `datetime` 은 sqlite·MySQL 의 이름이고 Postgres 는 `timestamp` 만 안다 — 거꾸로 `timestamp` 는
-   * sqlite 가 모른다. **다섯 드라이버에 다 통하는 이름이 없다.** 그래서 이름 고르는 일을 TypeORM 에
-   * 맡긴다(`emitDecoratorMetadata` 가 켜져 있어 `Date` 에서 드라이버별 타입을 고른다).
-   */
-  @Column()
-  @Field({ description: 'Server time when the command was dispatched.' })
-  eventTime: Date
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Client-supplied command id, for correlating with kernel logs.' })
-  commandId?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Command type (e.g. order.hold, equipment.repair).' })
-  commandType?: string
-
-  /* 'user' | 'ai' | 'automation' | 'unknown'. 모르면 unknown 이지 사람이 한 것으로 치지 않는다. */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: "Where the command originated: 'user' | 'ai' | 'automation' | 'unknown'." })
-  origin?: string
-
-  /*
-   * 승인 사유 — 사람이 쓰는 글이라 길이를 미리 자르지 않는다.
-   *
-   * 이름을 드라이버별로 고른다(2026-08-19): `text` 는 Oracle 이 모르고(그쪽은 `clob`), MySQL 계열은
-   * 긴 글에 `longtext` 를, MSSQL 은 `nvarchar(MAX)` 를 쓴다. 다중 DB 를 지키는 이 레포의 관행이 그렇다.
-   */
-  @Column({
-    nullable: true,
-    type:
-      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
-        ? 'longtext'
-        : DATABASE_TYPE == 'oracle'
-          ? 'clob'
-          : DATABASE_TYPE == 'mssql'
-            ? 'nvarchar'
-            : 'text',
-    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined
-  })
-  @Field({ nullable: true, description: 'Why this action — the rationale shown on the approval card.' })
-  reason?: string
-
-  /* ── 신원: 세션에서만 온다 ── */
-  /*
-   * **원본이 그래서 어떻게 했나** — 허락과 일어남 사이에 끼어 있는 것을 같은 행에 닫는다
-   * (ADR-0029 §1 결정 C, 2026-08-19).
-   *
-   * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다 — 어댑터가 오류 없이 실패하면 원장에는 승인만
-   * 남는다. 그래서 어댑터의 답을 되적는다.
-   *
-   *  · 비어 있음 — **원본에 묻지 않았다**(커널이 받은 명령이다). 「모른다」와 다르다.
-   *  · `unknown` — 물었는데 **답을 못 받았다**. 성공으로 적지 않는다.
-   *  · `applied` · `refused` — 원본이 답했다(둘 다 사실이다).
-   */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: "What the source did with it: 'applied' | 'refused' | 'unknown' (asked but no answer). Empty means the source was not asked — the kernel took the command." })
-  sourceOutcome?: string
-
-  /** 원본이 준 사유 코드 — 있으면 그대로 적는다(우리가 지어내지 않는다). */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Reason code the source returned, as it gave it.' })
-  sourceCode?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Approving user id, stamped by the server from the session.' })
-  actorId?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Approving user email, stamped by the server from the session.' })
-  actorEmail?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Approving user name, stamped by the server from the session.' })
-  actorName?: string
-
-  /* ── 결과: 거절도 남긴다 ── */
-  @Column({ default: false })
-  @Field({ description: 'Whether the kernel accepted the command.' })
-  accepted: boolean
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Language-neutral rejection code when the kernel refused.' })
-  errorCode?: string
-
-  /**
-   * 명령 인자 — **원형 그대로.** 무엇에 대한 명령이었는지가 감사의 핵심이라 요약하지 않는다.
-   * 지나치게 크면 자르되 `argsTruncated` 로 잘랐다는 사실을 남긴다(알리지 않고 버리지 않는다).
-   */
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'Command arguments as given.' })
-  args?: any
-
-  @Column({ default: false })
-  @Field({ description: 'True when args were too large and stored truncated.' })
-  argsTruncated: boolean
-
-  @CreateDateColumn()
-  @Field({ nullable: true, description: 'Timestamp when the audit row was written.' })
-  createdAt?: Date
-}