@things-factory/headless-twin 10.1.278 → 10.1.280

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

@@ -1,72 +0,0 @@
-import { Args, Ctx, Query, Resolver } from 'type-graphql'
-
-import { ListParam, getQueryBuilderFromListParams, getRepository, ScalarObject } from '@things-factory/shell'
-
-import { TwinAuditEvent } from './twin-audit-event.js'
-
-/*
- * 승인 기록 조회 — **감사의 기본 질문에 답한다.**
- *
- *   "요즘 무슨 조치가 나갔나"        → 최근순 목록
- *   "김현장이 승인한 것 전부"        → 행위자 검색(인덱스 있음)
- *   "AI 가 제안한 것만"              → origin 필터
- *   "거절된 시도"                    → accepted 필터
- *
- * 저널에 섞여 있을 때는 이 중 어느 것도 못 했다 — 행위자가 payload JSON 안이라 인덱스를 걸 수 없었다.
- */
-/** 시각 필터 값을 날짜로 — 못 읽는 값은 그대로 둔다(지어내지 않는다). */
-function toDateValue(v: any): any {
-  const one = (x: any) => {
-    if (x instanceof Date) return x
-    const t = typeof x === 'string' ? Date.parse(x) : NaN
-    return Number.isNaN(t) ? x : new Date(t)
-  }
-  return Array.isArray(v) ? v.map(one) : one(v)
-}
-
-@Resolver()
-export class TwinAuditQuery {
-  /* 조회 게이트는 달지 않는다 — 이 저장소의 규약이고(mutation-gate 검사가 정본을 지킨다),
-     도메인 필터가 테넌트 경계를 이미 지킨다. 테넌트를 넘어 읽는 계기판만 OPS_GATE 를 쓴다. */
-  @Query(returns => ScalarObject, {
-    nullable: true,
-    description:
-      'List twin command audit records (who approved what, and what the kernel answered) with the standard list contract, plus the total match count.'
-  })
-  async twinAuditList(
-    /* 표준 목록 계약은 `@Args` 로 펼쳐 받는다 — `@Arg` 로 받으면 type-graphql 이 입력 타입을
-       결정하지 못해 **스키마 조립 자체가 실패**한다(서버가 아예 안 뜬다). */
-    @Args(type => ListParam) params: ListParam,
-    @Ctx() context: ResolverContext
-  ): Promise<any> {
-    const domainId = context.state.domain?.id
-    if (!domainId) return { items: [], total: 0 }
-
-    const effective: ListParam = {
-      ...(params ?? ({} as ListParam)),
-      /* 기본 정렬 — 최근 것부터. 감사는 "요즘" 에서 시작한다. */
-      sortings: params?.sortings?.length ? params.sortings : [{ name: 'eventTime', desc: true }],
-      /* 시각 필터는 날짜로 옮겨서 넘긴다 — 문자열 그대로면 알리지 않고 0건이 된다(저널과 같은 이유). */
-      filters: (params?.filters ?? []).map(f => (f.name === 'eventTime' ? { ...f, value: toDateValue(f.value) } : f))
-    }
-
-    const qb = getQueryBuilderFromListParams({
-      repository: getRepository(TwinAuditEvent),
-      params: effective,
-      domain: context.state.domain,
-      alias: 'a',
-      /*
-       * `searchables` 는 전부 **실컬럼**이다 — 프레임워크 질의 빌더는 여기 없는 컬럼의 LIKE 를
-       * 경고 후 무시한다(인덱스 없는 전체 스캔 방지). 행위자로 찾는 것이 이 테이블을 구분한 이유다.
-       */
-      searchables: ['actorEmail', 'actorName', 'commandType', 'origin', 'errorCode', 'reason'],
-      sortables: ['eventTime', 'commandType', 'actorEmail', 'origin', 'accepted'],
-      /* 감사 목록은 사람이 읽는 속도로 본다 — 크게 퍼 오는 것이 이득이 아니다. */
-      defaultLimit: 50,
-      maxLimit: 200
-    })
-
-    const [items, total] = await qb.getManyAndCount()
-    return { items, total }
-  }
-}

package/server/service/twin-backfill/backfill-period-facts.ts

@@ -1,168 +0,0 @@
-import { getRepository } from '@things-factory/shell'
-
-import { TwinEvent } from '../twin-event/twin-event.js'
-import { TwinEngine } from '../../engine/twin-engine.js'
-import { ingestCanonicalRecords } from '../../engine/canonical-ingest.js'
-import { absoluteTime } from '../../engine/read-time.js'
-import { judgeBackfill, splitAlreadyThere } from './backfill-shape.js'
-
-/*
- * 지난 기록 채우기 — **저널에만 쓴다. 트윈의 「지금」을 건드리지 않는다.**
- *
- * ── 왜 라이브 문으로 넣을 수 없나 (2026-08-30) ──────────────────────────────
- * 커널의 상태는 「지금」이다. 늦게 온 옛 표본은 가드가 막는다(그렇게 만들었다). 지난 기록을 라이브
- * 문으로 넣으면 둘 중 하나다 — 가드에 막히거나, 트윈의 시계가 과거로 끌린다. 둘 다 나쁘다.
- *
- * 그래서 이 길은 저널에만 쓴다. 상태는 그대로 두고, 저널을 읽는 쪽(성과 계산·이력 화면)만 그 사실을
- * 보게 된다.
- *
- * ── 무엇을 받나 ────────────────────────────────────────────────────────────
- * **마감된 구간 사실만** 받는다. 시점의 관측(계량 표본·설비 상태·발전 적산)은 받지 않는다 — 그것들은
- * 커널의 상태를 바꾸는 사실이라, 상태를 건너뛰고 저널에만 넣으면 상태와 저널이 갈라진다.
- *
- * ── 같은 기간을 두 번 넣지 않는다 ──────────────────────────────────────────
- * 마감된 구간 사실은 정체성이 내용에 있다(커널 0.7.81: 종류·대상·시작·끝). 그 id 로 이미 있는 것을
- * 가려낸다. 저장소의 제약으로 막지 않는 이유는 드라이버가 다섯이고 충돌 처리가 제각각이기 때문이다 —
- * 구간 단위로 한 번 읽어 가려내는 편이 이식성이 있고 값도 싸다(한 시간에 한 줄이면 하루 24줄이다).
- *
- * ── 보존보다 오래된 것은 받지 않는다 ───────────────────────────────────────
- * 저널은 보존 기간이 지나면 지운다. 그보다 오래된 것을 채우면 다음 정리에서 지워진다. 조용히 넣고
- * 지워지면 아무도 모르므로, **거절하고 이유를 말한다.**
- */
-
-export interface BackfillResult {
-  /** 저널에 새로 적은 수. */
-  written: number
-  /** 이미 있어서 건너뛴 수 — 다시 읽어도 중복이 쌓이지 않는다는 뜻이다. */
-  skipped: number
-  /** 받지 않은 것과 그 이유. 조용히 버리지 않는다. */
-  refused: { record: unknown; reason: string }[]
-}
-
-/** 이 도메인의 보존 기간(일). 정책이 없으면 `undefined` — 그때는 오래됨을 판정하지 않는다. */
-async function retentionDaysOf(domainId: string): Promise<number | undefined> {
-  const perDomain = TwinEngine.retentionDaysOf ? await TwinEngine.retentionDaysOf(domainId).catch(() => undefined) : undefined
-  const days = perDomain ?? TwinEngine.JOURNAL_RETENTION_DAYS
-  return days && days > 0 ? days : undefined
-}
-
-/**
- * 지난 기록을 저널에 채운다.
- *
- * `records` 는 라이브와 **같은 모양**이다 — 커넥터가 다른 어휘를 배울 필요가 없다. 검증·갈림·id 만들기는
- * 커널의 유입이 그대로 한다(§`ingestCanonicalRecords`).
- */
-export async function backfillPeriodFacts(input: {
-  domainId: string
-  instanceId: string
-  records: unknown[]
-  /** 이 시각을 「지금」으로 본다 — 보존 판정의 기준. 시험이 시각을 정할 수 있게 받는다. */
-  nowMs?: number
-}): Promise<BackfillResult> {
-  const { domainId, instanceId, records } = input
-  const nowMs = input.nowMs ?? Date.now()
-  const refused: { record: unknown; reason: string }[] = []
-
-  if (!Array.isArray(records) || !records.length) return { written: 0, skipped: 0, refused }
-
-  /* 검증과 갈림은 라이브와 같은 것을 쓴다 — 두 벌이 되면 채운 사실과 관측한 사실이 다른 규칙을 지난다. */
-  const { accepted, rejected } = ingestCanonicalRecords(
-    records as any,
-    domainId,
-    new Date(nowMs).toISOString(),
-    /* 어느 트윈의 사실인가 — 마감된 구간의 이름이 이것으로 갈린다(커널 §`SubjectBasis`). */
-    TwinEngine.factScope(domainId, instanceId)
-  )
-  for (const r of rejected) refused.push({ record: r.record, reason: (r.errors ?? []).join(' · ') })
-
-  const days = await retentionDaysOf(domainId)
-
-  const judged = judgeBackfill(accepted as any[], { nowMs, retentionDays: days })
-  refused.push(...judged.refused)
-  const keep = judged.keep
-
-  if (!keep.length) {
-    TwinEngine.recordIngestResult(
-      domainId,
-      instanceId,
-      records.length,
-      refused.map(r => ({ record: r.record, errors: [r.reason] })),
-      nowMs,
-      0
-    )
-    return { written: 0, skipped: 0, refused }
-  }
-
-  /*
-   * 이미 있는 것을 가려낸다 — 그 구간의 그 종류만 읽는다(색인이 받쳐 준다). 페이로드의 id 로 견주고,
-   * 저장소 제약에 기대지 않는다(드라이버 다섯).
-   */
-  const times = keep.map(e => absoluteTime(e.eventTime)!.getTime())
-  const fromAt = new Date(Math.min(...times))
-  const toAt = new Date(Math.max(...times))
-  const types = [...new Set(keep.map(e => String(e.eventType)))]
-
-  const existing = await getRepository(TwinEvent)
-    .createQueryBuilder('e')
-    .select(['e.payload AS "payload"'])
-    .where('e.domain = :domainId', { domainId })
-    .andWhere('e.instanceId = :instanceId', { instanceId })
-    .andWhere('e.eventType IN (:...types)', { types })
-    .andWhere('e.eventTime BETWEEN :fromAt AND :toAt', { fromAt, toAt })
-    .getRawMany<{ payload: unknown }>()
-
-  const seen = new Set<string>()
-  for (const row of existing) {
-    const p: any = typeof row.payload === 'string' ? safeParse(row.payload) : row.payload
-    const id = p?.eventId
-    if (typeof id === 'string' && id) seen.add(id)
-  }
-
-  const { fresh, skipped } = splitAlreadyThere(keep, seen)
-  if (!fresh.length) {
-    TwinEngine.recordIngestResult(
-      domainId,
-      instanceId,
-      records.length,
-      refused.map(r => ({ record: r.record, errors: [r.reason] })),
-      nowMs,
-      skipped
-    )
-    return { written: 0, skipped, refused }
-  }
-
-  /*
-   * 리비전은 **쓴 순서**다(일어난 순서가 아니다). 지난 사실이 지금 번호를 받는 것이 맞다 — 저널을
-   * 시각으로 읽는 쪽은 `eventTime` 을 보고, 리비전은 같은 시각을 가릴 때만 쓴다.
-   */
-  const start = TwinEngine.journalHead(domainId, instanceId)
-  const items = fresh.map((event, i) => ({ event, revision: start + i + 1 }))
-
-  await TwinEngine.persistCarried(domainId, instanceId, items)
-  TwinEngine.advanceJournalHead(domainId, instanceId, items.length)
-
-  /*
-   * 장부에 적는다 — **유입을 부르는 곳은 모두 적는다.** 한 경로만 빠지면 그 트윈의 유입 건강이
-   * 「모름」으로 보인다(§`ingest-health-wiring`).
-   *
-   * 건네받지 못한 수(`undelivered`)는 **거절한 것과 이미 있어서 건너뛴 것의 합**이다. 건너뛴 것은
-   * 버려진 것이 아니지만 이번에 새로 적히지도 않았다 — 「통과」로 세면 채운 양이 실제보다 커 보인다.
-   */
-  TwinEngine.recordIngestResult(
-    domainId,
-    instanceId,
-    records.length,
-    refused.map(r => ({ record: r.record, errors: [r.reason] })),
-    nowMs,
-    skipped
-  )
-  return { written: items.length, skipped, refused }
-}
-
-function safeParse(text: string): unknown {
-  try {
-    return JSON.parse(text)
-  } catch {
-    return undefined
-  }
-}

package/server/service/twin-backfill/backfill-shape.ts

@@ -1,86 +0,0 @@
-/*
- * 지난 기록 채우기의 **판단** — 저장소를 모르는 순수 함수.
- *
- * 무엇을 받고 무엇을 거절하는지가 이 파일에 다 있다. 저장소를 아는 코드(`backfill-period-facts`)는
- * 이 판단을 부르고 쓰기만 한다. 갈라 두는 이유는 이 저장소가 이미 쓰는 방식이다 —
- * 판단은 시험이 데이터베이스 없이 지킬 수 있어야 한다(§`event-type-split-shape`).
- */
-
-/** 이 길이 받는 사실 — 마감된 구간을 말하는 것들. */
-export const PERIOD_FACTS: readonly string[] = [
-  'energy.usage.period',
-  'energy.generation.period',
-  'energy.generation.price',
-  'energy.tariff.basis',
-  'energy.bill'
-]
-
-export interface BackfillJudgement {
-  /** 저널에 넣어도 되는 것. */
-  keep: any[]
-  /** 받지 않은 것과 그 이유 — 조용히 버리지 않는다. */
-  refused: { record: unknown; reason: string }[]
-}
-
-/**
- * 무엇을 채울 수 있나.
- *
- * 세 가지로 거절한다.
- *
- *   마감된 구간이 아니다   상태를 바꾸는 사실을 저널에만 넣으면 상태와 저널이 갈라진다
- *   아직 오지 않은 시각    지난 기록이 아니다
- *   보존보다 오래됐다      넣어도 다음 정리에서 지워진다 — 조용히 사라지느니 거절한다
- */
-export function judgeBackfill(
-  envelopes: readonly any[],
-  opts: { nowMs: number; retentionDays?: number }
-): BackfillJudgement {
-  const keep: any[] = []
-  const refused: { record: unknown; reason: string }[] = []
-  const horizonMs = opts.retentionDays === undefined ? undefined : opts.nowMs - opts.retentionDays * 86_400_000
-
-  for (const env of envelopes) {
-    const type = String(env?.eventType ?? '')
-    if (!PERIOD_FACTS.includes(type)) {
-      refused.push({
-        record: env,
-        reason:
-          `${type} 는 마감된 구간 사실이 아니다 — 이 길은 저널에만 쓰므로, 상태를 바꾸는 사실을 여기로 넣으면 ` +
-          '상태와 저널이 갈라진다. 라이브 문으로 보내라'
-      })
-      continue
-    }
-    const atMs = Date.parse(String(env?.eventTime ?? ''))
-    if (!Number.isFinite(atMs)) {
-      refused.push({ record: env, reason: '사건 시각을 읽을 수 없다' })
-      continue
-    }
-    if (atMs > opts.nowMs) {
-      refused.push({ record: env, reason: `아직 오지 않은 시각이다(${env?.eventTime}) — 지난 기록이 아니다` })
-      continue
-    }
-    if (horizonMs !== undefined && atMs < horizonMs) {
-      refused.push({
-        record: env,
-        reason:
-          `보존 기간(${opts.retentionDays}일)보다 오래됐다(${env?.eventTime}) — 넣어도 다음 정리에서 지워진다. ` +
-          '더 뒤까지 보려면 보존 기간을 늘려야 한다'
-      })
-      continue
-    }
-    keep.push(env)
-  }
-
-  return { keep, refused }
-}
-
-/**
- * 이미 있는 것을 가려낸다 — **정체성은 내용에 있다**(커널 0.7.81).
- *
- * 저장소의 제약으로 막지 않는 이유는 드라이버가 다섯이고 충돌 처리가 제각각이기 때문이다.
- * 구간 단위로 한 번 읽어 가려내는 편이 이식성이 있고 값도 싸다.
- */
-export function splitAlreadyThere(keep: readonly any[], existingIds: ReadonlySet<string>): { fresh: any[]; skipped: number } {
-  const fresh = keep.filter(e => typeof e?.eventId === 'string' && e.eventId && !existingIds.has(e.eventId))
-  return { fresh, skipped: keep.length - fresh.length }
-}

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

@@ -1,3 +0,0 @@
-import { TwinBackfillResolver } from './twin-backfill-resolver.js'
-
-export const resolvers = [TwinBackfillResolver]

package/server/service/twin-backfill/twin-backfill-resolver.ts

@@ -1,35 +0,0 @@
-import { Arg, Ctx, Directive, Mutation, Resolver } from 'type-graphql'
-import { ScalarObject } from '@things-factory/shell'
-
-import { backfillPeriodFacts } from './backfill-period-facts.js'
-
-/*
- * 지난 기록 채우기의 **문** — 커넥터가 트윈이 없던 동안의 날들을 뒤늦게 넣는다.
- *
- * ── 왜 문을 따로 두나 (2026-08-30) ────────────────────────────────────────
- * 라이브 유입과 판단이 다르다. 라이브는 트윈의 「지금」을 바꾸고, 이쪽은 저널에만 쓴다. 같은 문으로
- * 받으면 옛 표본이 가드에 막히거나 트윈의 시계가 과거로 끌린다(§`backfill-period-facts`).
- *
- * 레코드의 **모양은 라이브와 같다** — 커넥터가 다른 어휘를 배울 필요가 없다. 다른 것은 받는 종류뿐이고,
- * 그 판단은 커널의 유입과 `judgeBackfill` 이 한다.
- *
- * ── 왜 이 파일이 늦게 생겼나 ──────────────────────────────────────────────
- * 채우기 자체는 만들어 두고 **부르는 곳을 만들지 않아** 쓸 수 없는 채로 있었다. 8월 29일 발전량을
- * 되살리려다 드러났다. 같은 부류를 그날 두 번 겪었다(커널의 발전 기간 문도 없었다).
- */
-@Resolver()
-export class TwinBackfillResolver {
-  /* 트윈의 모든 변경과 같은 게이트다(ADR-0027) — 저널에 사실을 적는 일이므로 변경이다. */
-  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => ScalarObject, {
-    description:
-      'Backfill closed-period facts into a twin journal without touching its live state. Records use the same shape as live ingest; only closed-period facts are accepted (usage/generation periods, generation price, tariff basis, bill). Point-in-time observations are refused with a reason, as are times beyond journal retention. Re-running is safe: a period already present is skipped, because a closed period is identified by its content. Returns { written, skipped, refused }.'
-  })
-  async backfillTwinPeriodFacts(
-    @Arg('instanceId') instanceId: string,
-    @Arg('records', type => [ScalarObject]) records: unknown[],
-    @Ctx() context: ResolverContext
-  ): Promise<{ written: number; skipped: number; refused: { record: unknown; reason: string }[] }> {
-    return await backfillPeriodFacts({ domainId: context.state.domain.id, instanceId, records })
-  }
-}

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

@@ -1,3 +0,0 @@
-import { TwinControlMutation } from './twin-control-mutation.js'
-
-export const resolvers = [TwinControlMutation]

package/server/service/twin-control/twin-control-mutation.ts

@@ -1,150 +0,0 @@
-import { twinError } from '../../engine/log.js'
-import { Arg, Ctx, Mutation, Query, Resolver, Directive } from 'type-graphql'
-
-import { validateScenario } from '@operato/ops-contract'
-
-import { ScalarObject } from '@things-factory/shell'
-
-import { getRepository } from '@things-factory/shell'
-
-import { TwinEngine } from '../../engine/index.js'
-import { TwinAuditEvent } from '../twin-audit/twin-audit-event.js'
-import { buildCommandAudit } from '../twin-audit/command-audit.js'
-/* 구동은 원본을 지난다(ADR-0029 §8) — 트윈 런타임을 직접 잡지 않는다. */
-import { routeControl, controlCapabilityOf } from '../reference/control-routing.js'
-
-/*
- * 트윈 Command·Scenario 채널 — 상향 mutation.
- * Command: runtime.dispatch(행위). Scenario: runtime.scenario.load/start/pause/setSpeed(예측 자극).
- * (State 하향은 twin-state subscription. tick 은 워커.)
- *
- * 인가: data 구독 리졸버와 대칭으로, 대상 인스턴스가 **호출자 도메인 소속**인지 검증한다(cross-tenant 커맨드 주입 차단).
- * command 채널은 sim 상태를 변이하므로 도메인 스코프가 필수.
- */
-@Resolver()
-export class TwinControlMutation {
-  /** Command 채널 — 오더 hold/resume/release 등. 커널 dispatch 로 위임, ack{accepted,error} 반환. */
-  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => ScalarObject, { description: 'dispatch a twin command (order.hold/resume/release …). Returns {accepted, error?}.' })
-  async dispatchTwinCommand(
-    @Arg('instanceId') instanceId: string,
-    @Arg('command', type => ScalarObject) command: any,
-    @Ctx() context: ResolverContext
-  ): Promise<{ accepted: boolean; error?: string; errorCode?: string; errorParams?: Record<string, string | number> }> {
-    const domainId = context.state.domain?.id
-    if (!domainId) return { accepted: false, error: 'no-domain', errorCode: 'no-domain' }
-    /*
-     * 라우팅은 엔진이 한다 — 예전에는 여기서 `inst.runtime.dispatch` 를 곧바로 불렀고, `runtime` 이
-     * 시뮬에만 있어서 미러 트윈에서는 이 한 줄이 TypeError 로 터졌다(깔끔한 거절이 아니라 실패).
-     * 권위(모드) × 성격(주석/액추에이션) 판정은 한 곳에만 둔다.
-     */
-    /* 원본을 그대로 감사에 넘긴다 — 무엇이 들어왔는지가 기록의 대상이다(정규화는 감사 모듈이 한다). */
-    const cmdWithOrigin = command
-    const ack = await TwinEngine.dispatchCommand(domainId, instanceId, command)
-    /* 라이브 구조 변이(resource.add)는 저장 model 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
-    if (ack?.accepted && command?.type === 'resource.add') {
-      await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => twinError('twin syncBoardEquipment fail', err))
-    }
-    /*
-     * 감사 기록 — 승인 게이트가 앞을 막고, 이 줄이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를
-     * 증명할 수 있다. 커널이 거절한 것도 남긴다 — 무엇을 시도했는지가 감사의 절반이다.
-     *
-     * 기록이 실패해도 커맨드 결과는 그대로 돌려준다. 감사가 본업을 막으면 안 되지만, 실패를 삼키지도
-     * 않는다(로그에 남긴다) — 알리지 않고 안 남으면 나중에 "기록이 없다" 와 "일이 없었다" 를 구분 못 한다.
-     */
-    try {
-      const audit = buildCommandAudit({ command: cmdWithOrigin, ack, actor: context.state.user, at: new Date() })
-      const repo = getRepository(TwinAuditEvent)
-      await repo.save(repo.create({ domain: context.state.domain, instanceId, ...audit }))
-    } catch (err) {
-      twinError(`[twin-control] command audit not recorded for "${instanceId}"`, err)
-    }
-
-    /* 거절 사유는 **언어 중립 코드**로 함께 돌려준다 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */
-    return { accepted: !!ack?.accepted, error: ack?.error, errorCode: ack?.errorCode, errorParams: ack?.errorParams }
-  }
-
-  /**
-   * 구동 채널 — **원본을 지난다**(ADR-0029 §8).
-   *
-   * ── 무엇이 바뀌었나 (2026-08-19) ──────────────────────────────────────────
-   * 예전에는 이 문이 `TwinEngine.runtime(...).scenario` 를 **직접** 잡았다. 시뮬만 할 수 있는 일(자극·배속·
-   * 정지)이 계약 밖의 지름길로 들어온 셈이고, 실 시스템에는 그 자리가 아예 없었다. 이제 길은 하나다:
-   * 트윈 → 그 트윈의 원본 → 어댑터가 **선언한** `control` 능력. 선언하지 않은 원본에는 문이 열리지 않고,
-   * 그 사실을 사유 코드로 말한다(`not-declared`) — 실 WMS 가 정지되지 않는 것은 결손이 아니다.
-   *
-   * 반환을 Boolean 에서 객체로 바꿨다: 예전에는 거절 사유를 실을 자리가 없어 **로그로만** 남겼다.
-   * 화면은 왜 안 되는지 알 수 없었다.
-   */
-  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => ScalarObject, {
-    description:
-      "Drive the source behind a twin: stimulus | start | pause | speed | reset. The command goes through the source adapter's declared control capability — a source that does not declare it refuses with code 'not-declared' (a real system is not paused or seeded, and that is a fact rather than a gap). Returns { ok, code?, detail? }."
-  })
-  async controlTwinSource(
-    @Arg('instanceId') instanceId: string,
-    @Arg('action') action: string,
-    @Ctx() context: ResolverContext,
-    @Arg('scenario', type => ScalarObject, { nullable: true }) scenario?: any,
-    @Arg('speed', { nullable: true }) speed?: number
-  ): Promise<any> {
-    const domainId = context.state.domain?.id
-    if (!domainId) return { ok: false, code: 'no-domain' }
-    const allowed = ['stimulus', 'start', 'pause', 'speed', 'reset']
-    if (!allowed.includes(action)) return { ok: false, code: 'unsupported-action', detail: `one of ${allowed.join(' | ')}` }
-    /*
-     * **잘못된 선언은 문 앞에서 막는다.** 예전에는 검증 없이 실었고, 다음 tick 에서 `rate.meanPerHour` 를
-     * 읽다 터져 **서버 프로세스가 내려갔다**(클라이언트가 보낸 값 하나로 앱 전체가 죽었다). 규칙은 커널이
-     * 들고 있다(계약의 주인) — 호스트가 따로 만들면 방언이 생긴다.
-     */
-    if (action === 'stimulus') {
-      const v = validateScenario(scenario)
-      if (v.ok === false) return { ok: false, code: 'invalid', detail: v.errorCode, params: v.errorParams }
-    }
-    if (action === 'speed' && !(Number(speed) > 0)) return { ok: false, code: 'invalid', detail: 'speed must be greater than 0' }
-
-    /*
-     * **구동도 사람이 한 일이다 — 남긴다** (ADR-0029 §1 결정 C, 2026-08-19).
-     *
-     * 이 문은 감사를 아예 남기지 않았다. 그런데 자극을 바꾸고 배속을 올리고 원본을 멈추는 것은 그 트윈의
-     * 사실을 바꾸는 행위다 — 커맨드 채널은 남기는데 이쪽이 비어 있으면, 나중에 「무엇이 이 공장을
-     * 흔들었나」에 답할 수 없다.
-     *
-     * 결정 C 그대로: 게이트는 여기 남고(위 `@privilege`), **원본의 답을 같은 행에 닫는다.** 답을 못 받으면
-     * `unknown` 이다 — 성공으로 적지 않는다.
-     */
-    let result: { ok: boolean; code?: string; detail?: string }
-    try {
-      result = await routeControl(domainId, instanceId, { action: action as any, scenario, speed: speed != null ? Number(speed) : undefined })
-    } catch (e: any) {
-      result = { ok: false, code: 'failed', detail: e?.message ?? 'control failed' }
-    }
-    try {
-      const audit = buildCommandAudit({
-        /* 커맨드 채널과 같은 모양으로 적는다 — 감사를 읽는 쪽이 두 어휘를 배우지 않게. */
-        command: { type: `source.${action}`, origin: 'user', args: { ...(scenario ? { scenario } : {}), ...(speed != null ? { speed } : {}) } },
-        /* 게이트는 통과했다(여기까지 왔다) — 그 사실과 원본의 답은 다른 칸이다. */
-        ack: { accepted: true },
-        source: { answered: typeof result?.ok === 'boolean', ok: result?.ok, code: result?.code },
-        actor: context.state.user,
-        at: new Date()
-      })
-      const repo = getRepository(TwinAuditEvent)
-      await repo.save(repo.create({ domain: context.state.domain, instanceId, ...audit }))
-    } catch (err) {
-      /* 기록이 실패해도 결과는 돌려준다 — 다만 삼키지 않는다(「기록 없음」과 「일 없음」을 구별해야 한다). */
-      twinError(`[twin-control] source control audit not recorded for "${instanceId}"`, err)
-    }
-    return result
-  }
-
-  /** 이 트윈의 원본이 **무엇을 받을 수 있나** — 화면이 버튼을 열기 전에 묻는 자리. */
-  @Query(returns => ScalarObject, {
-    description: "What the source behind this twin can do: its declared capabilities ('live', 'control'). Empty when the twin has no source or its adapter declares nothing."
-  })
-  async twinSourceCapability(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any> {
-    const domainId = context.state.domain?.id
-    if (!domainId) return { capabilities: [] }
-    return controlCapabilityOf(domainId, instanceId)
-  }
-}

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

@@ -1,3 +0,0 @@
-import { TwinEvent } from './twin-event.js'
-
-export const entities = [TwinEvent]

package/server/service/twin-event/journal-count.ts

@@ -1,53 +0,0 @@
-/*
- * 저널을 **상한까지만 센다** — 세는 것도 읽는 것이다 (2026-08-22).
- *
- * ── 왜 (실측) ───────────────────────────────────────────────────────────────
- * 조건에 맞는 행을 전부 세는 질의는 행을 실어 오지 않아도 비싸다. 개발 저널에서 트윈 하나가 358만
- * 행이었고 그 한 번이 **5.32초**였다. 색인만 상한까지 읽으면 같은 조건에서 **0.04초**다(130배).
- *
- * 그 5초 동안 이벤트 루프는 다른 요청을 처리하지 못한다 — 이력 화면 한 번, 준비도 화면 한 번이
- * 사용자에게는 「눌렀는데 아무 반응이 없다」로 나타난다. 준비도 화면은 그런 세기를 **넷** 했다.
- *
- * ── 규율 ────────────────────────────────────────────────────────────────────
- * 세는 목적이 둘 중 하나다.
- *  ① **판정** — 「한 건이라도 있나」. 그때는 하나만 찾으면 끝이다(`anyJournalRow`).
- *  ② **표시** — 사람에게 수를 보인다. 그때는 상한까지 세고, 넘으면 **모른다고 말한다**(`countUpTo`).
- *
- * 상한을 넘었을 때 상한값을 전체로 적으면 화면이 거짓을 말한다. 그래서 `capped` 를 함께 낸다 —
- * 없는 것과 모르는 것을 가르는 이 프로젝트의 규율이 세기에도 같이 적용된다.
- */
-import type { ObjectLiteral, Repository } from 'typeorm'
-
-/** 표시용 세기의 기본 상한 — 화면이 한 번에 보여 줄 범위를 훨씬 넘는 값. */
-export const JOURNAL_COUNT_CAP = 10_000
-
-export interface CappedCount {
-  /** 센 수. `capped` 면 상한까지만 센 값이므로 **전체가 아니다**. */
-  count: number
-  /** 상한을 넘었나 — 그때 전체 수는 모르는 것이 사실이다. */
-  capped: boolean
-}
-
-/**
- * 상한까지만 세기 — 키 컬럼만 읽으므로 행 본문을 만들지 않는다.
- *
- * `count()` 를 쓰지 않는 이유: 그것은 상한을 받지 않는다(조건에 맞는 전부를 센다).
- */
-export async function countUpTo<T extends ObjectLiteral>(
-  repo: Repository<T>,
-  where: any,
-  cap = JOURNAL_COUNT_CAP
-): Promise<CappedCount> {
-  const rows = await repo.find({ where, select: ['id'] as any, take: cap + 1 })
-  return rows.length > cap ? { count: cap, capped: true } : { count: rows.length, capped: false }
-}
-
-/**
- * 한 건이라도 있나 — **판정에는 수가 필요 없다.**
- *
- * 예전에는 전부 센 뒤 `> 0` 을 봤다. 그 답을 얻는 데 358만 행을 세고 있었다.
- */
-export async function anyJournalRow<T extends ObjectLiteral>(repo: Repository<T>, where: any): Promise<boolean> {
-  const rows = await repo.find({ where, select: ['id'] as any, take: 1 })
-  return rows.length > 0
-}