@things-factory/headless-twin 10.0.12 → 10.0.13

package/server/index.ts

@@ -3,10 +3,12 @@ export * from './service/index.js'
 /* 스키마 이력 — 프레임워크가 `migrations` export 를 모아 실행한다(`run migration`). */
 export { migrations } from './migrations/index.js'
 
+import { twinLog, twinError } from './engine/log.js'
 import './routes.js'
 
 import { TwinEngine } from './engine/index.js'
 import { resumeReferenceLiveFeeds } from './service/reference/reference-live.js'
+import { installIngestWindowWriter } from './service/twin-ingest-window/index.js'
 
 /*
  * 모듈 부팅 — **도는 트윈을 되살린다.**
@@ -19,10 +21,41 @@ import { resumeReferenceLiveFeeds } from './service/reference/reference-live.js'
  */
 process.on('bootstrap-module-start' as any, async ({ app, config, client }: any) => {
   try {
+    /*
+     * 닫힌 인제스트 창을 표로 옮기는 문을 먼저 연다 — 트윈을 되살리기 **전에** 등록해야 첫 창부터
+     * 남는다. 커널 층은 저장 계층을 모르므로 이 등록이 그 둘을 잇는 유일한 자리다.
+     */
+    installIngestWindowWriter()
+    /*
+     * **저널 보존 기간은 선언에서 온다** — 코드에 박아 두지 않는다(2026-08-22).
+     *
+     * 실측: 개발 저널이 시간당 581,794행 · 0.85GB(하루 20GB) 로 자랐고 지우는 것이 없었다. 그런데
+     * 「며칠까지 남기나」는 **배포마다 갈리는 사실**이다 — 개발은 짧아도 되고 실증은 길어야 한다.
+     *
+     * 선언이 없으면 **아무것도 지우지 않는다.** 조용히 지우는 편이 조용히 쌓는 것보다 나쁘다.
+     * 값은 스냅샷 TTL(7일)보다 짧을 수 없다 — 엔진이 그것을 올려 주고 그 사실을 말한다.
+     */
+    /*
+     * 읽는 순서: **환경변수 → 설정 → 없음.**
+     *
+     * 설정(`config.twin.journalRetentionDays`)이 배포의 선언이고, 환경변수
+     * (`TWIN_JOURNAL_RETENTION_DAYS`)는 그것을 **그 자리에서** 덮는다. 컨테이너로 도는 배포에서는
+     * 파일을 고치지 않고 값을 바꿀 수 있어야 하고, 개발에서도 그 편이 빠르다.
+     *
+     * 둘 다 없으면 **아무것도 지우지 않는다.**
+     */
+    const fromEnv = Number(process.env.TWIN_JOURNAL_RETENTION_DAYS ?? 0)
+    const fromConfig = Number(config?.get?.('twin')?.journalRetentionDays ?? 0)
+    const retentionDays = fromEnv > 0 ? fromEnv : fromConfig
+    if (retentionDays > 0) {
+      TwinEngine.JOURNAL_RETENTION_DAYS = retentionDays
+      twinLog(`[twin] journal retention ${retentionDays}일 (${fromEnv > 0 ? '환경변수' : '설정'})`)
+    }
+
     await TwinEngine.bootstrap()
     await resumeReferenceLiveFeeds()
-    console.log('Headless Twin host has started.')
+    twinLog('Headless Twin host has started.')
   } catch (ex) {
-    console.error('Headless Twin host failed to start.', ex)
+    twinError('Headless Twin host failed to start.', ex)
   }
 })

package/server/migrations/1786100000000-PromoteEventActionAndSyncWarnings.ts

@@ -0,0 +1,54 @@
+import { MigrationInterface, QueryRunner, TableColumn, TableIndex } from 'typeorm'
+
+/**
+ * 두 계측을 위한 컬럼 둘.
+ *
+ * ① `twin_events.action` — EPCIS 행위(ADD/OBSERVE/DELETE) 승격.
+ *    되풀어 읽는 스냅샷은 원리적으로 `DELETE` 를 못 낸다. 그래서 「이 트윈이 반출을 한 번이라도
+ *    접었는가」가 진짜 delta 피드의 증거인데, 값이 `payload`(simple-json = TEXT) 안에 있는 동안에는
+ *    5개 드라이버 어디에서도 그 질문을 할 수 없었다(DB별 JSON 연산자 금지).
+ *
+ * ② `twin_references.last_warning_count` — 마지막 동기에서 못 옮긴 값의 수.
+ *    세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 조용히 성공한다.
+ *
+ * **둘 다 nullable, 기본값 없음.** 기본값 0 을 깔면 「없었다」와 「세지 않았다」가 같아지고, 그
+ * 구분이 단계 판정의 전부다(옛 행은 모르는 것이 맞다 — 채워 넣지 않는다).
+ *
+ * 인덱스 `ix_twin_event_6` 는 저널이 큰 환경에서 생성에 시간이 걸린다. 그래도 만드는 이유:
+ * 없으면 「반출을 접었나」가 그 인스턴스 저널 전량 주사가 되고, 반출이 **없는** 경우(초기 상태이자
+ * 가장 흔한 경우)가 항상 최악이다.
+ *
+ * 멱등: 이미 있으면 아무것도 하지 않는다. TypeORM API 만 쓴다(raw SQL 금지 — 드라이버 5종).
+ */
+const EVENTS = 'twin_events'
+const REFS = 'twin_references'
+const ACTION = 'action'
+const WARN = 'last_warning_count'
+const IX = 'ix_twin_event_6'
+
+export class PromoteEventActionAndSyncWarnings1786100000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    const events = await queryRunner.getTable(EVENTS)
+    if (events && !events.columns.some(c => c.name === ACTION)) {
+      await queryRunner.addColumn(events, new TableColumn({ name: ACTION, type: 'varchar', length: '16', isNullable: true }))
+    }
+    const withColumn = await queryRunner.getTable(EVENTS)
+    if (withColumn && withColumn.columns.some(c => c.name === ACTION) && !withColumn.indices.some(i => i.name === IX)) {
+      await queryRunner.createIndex(withColumn, new TableIndex({ name: IX, columnNames: ['domain_id', 'instance_id', ACTION] }))
+    }
+
+    const refs = await queryRunner.getTable(REFS)
+    if (refs && !refs.columns.some(c => c.name === WARN)) {
+      await queryRunner.addColumn(refs, new TableColumn({ name: WARN, type: 'int', isNullable: true }))
+    }
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    const events = await queryRunner.getTable(EVENTS)
+    if (events?.indices.some(i => i.name === IX)) await queryRunner.dropIndex(events, IX)
+    const events2 = await queryRunner.getTable(EVENTS)
+    if (events2?.columns.some(c => c.name === ACTION)) await queryRunner.dropColumn(events2, ACTION)
+    const refs = await queryRunner.getTable(REFS)
+    if (refs?.columns.some(c => c.name === WARN)) await queryRunner.dropColumn(refs, WARN)
+  }
+}

package/server/migrations/1786200000000-CarryLiveFeedCursor.ts

@@ -0,0 +1,53 @@
+import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm'
+
+/**
+ * `twin_references.live_cursor` — **어디까지 읽었나**를 재기동 너머로 잇는다.
+ *
+ * ── 무엇이 조용히 사라지고 있었나 (2026-08-23 실측) ─────────────────────────
+ * 라이브 어댑터가 붙을 때마다 `Date.now() − 되돌아볼 날수` 로 창을 새로 만들었다. 그래서 **재기동마다
+ * 미러의 과거가 잘렸다** — 작업 2,855 → 2,820(그 사이 8시간이 흐른 만큼). 미러가 아는 것이 「원본의
+ * 사실」이 아니라 「창의 함수」였고, 화면은 그 수를 보이면서 그 사실을 말하지 않았다.
+ *
+ * 같은 원본에서 잰 규모가 그 값을 말한다: 작업지시 77,594건 중 창이 읽는 것이 3,039건(3.9%)이다.
+ *
+ * ── 왜 표인가 (캐시가 아니라) ───────────────────────────────────────────────
+ * 커널이 갈림을 이미 적어 두었다(§`hydrateContinuity`): 「원천이 **애초에 다시 말해 주지 않는 축**」은
+ * 재기동 연속성으로 이어받는다. 「우리가 어디까지 읽었나」가 정확히 그 성질이다.
+ *
+ * 그리고 스냅샷 체크포인트와 성질이 다르다: 그쪽은 잃어도 원천이 정정해 준다(그래서 TTL 캐시로 족하다).
+ * **이 값은 잃으면 원천에 묻지 않게 된다** — 창이 다시 미끄러지고, 그 손실은 오류 없이 조용하다.
+ * 만료되는 자리에 둘 수 없다.
+ *
+ * ── 모양 ────────────────────────────────────────────────────────────────────
+ * `{ streams: { [흐름]: { since?, seen: string[] } }, firstAttachedAt? }`
+ *
+ * **흐름 이름은 어댑터가 정한다** — 원본마다 흐름 수와 뜻이 다르다(첫 실 원본은 재고·오더·로트·투입 넷).
+ * 이 층은 열쇠로만 다룬다. 계약이 이름을 닫으면 새 원본마다 계약을 고치게 된다.
+ *
+ * `firstAttachedAt` 은 「언제부터 아는가」다 — 커널은 상한만 안다(`nowTime`). 둘이 함께 「이 트윈이
+ * 아는 구간」이고, 화면이 수를 보일 때 그 구간을 말해야 한다.
+ *
+ * **nullable, 기본값 없음.** `null` = 한 번도 붙지 않았다는 사실이고, 그때만 되돌아볼 날수로 첫 창을
+ * 만든다. 빈 객체를 기본으로 깔면 「첫 붙음」과 「이어 붙음」이 같아지고, 그 구분이 이 컬럼의 전부다.
+ *
+ * `simple-json` = TEXT 이므로 드라이버 다섯을 그대로 지난다(DB별 JSON 타입·연산자 금지).
+ * 멱등: 이미 있으면 아무것도 하지 않는다. TypeORM API 만 쓴다(raw SQL 금지).
+ */
+const REFS = 'twin_references'
+const CURSOR = 'live_cursor'
+
+export class CarryLiveFeedCursor1786200000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    const refs = await queryRunner.getTable(REFS)
+    if (refs && !refs.columns.some(c => c.name === CURSOR)) {
+      await queryRunner.addColumn(refs, new TableColumn({ name: CURSOR, type: 'text', isNullable: true }))
+    }
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    const refs = await queryRunner.getTable(REFS)
+    if (refs && refs.columns.some(c => c.name === CURSOR)) {
+      await queryRunner.dropColumn(refs, CURSOR)
+    }
+  }
+}

package/server/migrations/index.ts

@@ -3,5 +3,11 @@
  * 파일마다 하나씩 export 하고 여기서 모아 `server/index.ts` 가 내보낸다.
  */
 import { RenameTwinInstanceBoardToModel1786000000000 } from './1786000000000-RenameTwinInstanceBoardToModel.js'
+import { PromoteEventActionAndSyncWarnings1786100000000 } from './1786100000000-PromoteEventActionAndSyncWarnings.js'
+import { CarryLiveFeedCursor1786200000000 } from './1786200000000-CarryLiveFeedCursor.js'
 
-export const migrations = [RenameTwinInstanceBoardToModel1786000000000]
+export const migrations = [
+  RenameTwinInstanceBoardToModel1786000000000,
+  PromoteEventActionAndSyncWarnings1786100000000,
+  CarryLiveFeedCursor1786200000000
+]

package/server/service/index.ts

@@ -1,6 +1,7 @@
 /* EXPORT ENTITY TYPES */
 export * from './twin-event/twin-event.js'
 export * from './twin-audit/twin-audit-event.js'
+export * from './twin-ingest-window/twin-ingest-window.js'
 export * from './twin-instance/twin-instance.js'
 export * from './twin-space/twin-space.js'
 export * from './twin-space/twin-space-representation.js'
@@ -14,6 +15,10 @@ export * from './reference/reference-adapter.js'
 export * from './reference/reference-live.js'
 export * from './reference/twin-reference.js'
 export * from './reference/template-registry.js'
+/* 커넥터 점검 하네스 — 실 원본에 붙여 무엇이 채워지고 무엇이 비는지 센다(앱을 띄우지 않는다). */
+export * from './reference/reference-probe.js'
+/* 읽은 뒤의 총평(사실 층) — 화면이 표로 그리고, 더 알고 싶을 때 AI 가 이 사실만 근거로 서술한다. */
+export * from './reference/reference-assessment.js'
 /* 도메인 어휘 카탈로그 조합(커널 SSOT 노출) — 서버측 소비자(board-ai 도구 등)가 같은 형태를 쓰도록. */
 export * from './twin-lifecycle/domain-catalog.js'
 
@@ -28,15 +33,19 @@ import { entities as TwinReferenceEntities, resolvers as TwinReferenceResolvers
 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'
+/* 인제스트 창 — 동기화 추이를 재기동 뒤에도 이어 보기 위한 행(리졸버 없음: 메모리 장부가 조회를 답한다). */
+import { entities as TwinIngestWindowEntities, resolvers as TwinIngestWindowResolvers } from './twin-ingest-window/index.js'
 import { resolvers as TwinLifecycleResolvers } from './twin-lifecycle/index.js'
 import { resolvers as TwinJournalResolvers } from './twin-journal/index.js'
 import { resolvers as TwinForecastResolvers } from './twin-forecast/index.js'
 import { resolvers as TwinAttentionResolvers } from './twin-attention/index.js'
 import { resolvers as TwinMetricsResolvers } from './twin-metrics/index.js'
+import { resolvers as TwinReadinessResolvers } from './twin-readiness/index.js'
 
 export const entities = [
   /* ENTITIES */
   ...TwinEventEntities,
+  ...TwinIngestWindowEntities,
   ...TwinAuditEntities,
   ...TwinInstanceEntities,
   ...TwinStructureEntities,
@@ -61,6 +70,8 @@ export const schema = {
     ...TwinForecastResolvers,
     ...TwinAttentionResolvers,
     ...TwinMetricsResolvers,
+    ...TwinReadinessResolvers,
+    ...TwinIngestWindowResolvers,
     ...TwinModelResolvers,
     ...TwinSpaceResolvers,
     ...TwinTargetResolvers,

package/server/service/reference/discovery-result.ts

@@ -86,7 +86,7 @@ export function failed<S>(error: DiscoveryError): DiscoveryResult<S> {
   return { sites: [], error }
 }
 
-/** 어댑터가 던진 것에서 사람이 읽을 사유를 뽑는다 — 형태를 가정하지 않는다. */
+/** 어댑터가 오류를 낸 것에서 사람이 읽을 사유를 뽑는다 — 형태를 가정하지 않는다. */
 export function detailOf(e: unknown): string {
   if (e instanceof Error && e.message) return e.message
   if (typeof e === 'string' && e) return e

package/server/service/reference/index.ts

@@ -1,6 +1,11 @@
 import { TwinReferenceResolver } from './reference-resolver.js'
+import { TwinReferenceProgressSubscription } from './reference-progress-subscription.js'
 import { TwinReference } from './twin-reference.js'
 
 export const entities = [TwinReference]
-export const resolvers = [TwinReferenceResolver]
+export const resolvers = [TwinReferenceResolver, TwinReferenceProgressSubscription]
 export * from './control-routing.js'
+/* 진행 단계 어휘 — **모든 커넥터가 같은 낱말로 말한다.** 화면은 단계마다 번역 하나만 두면 된다. */
+export * from './reference-progress.js'
+/* 커넥터 점검 하네스 — 실 원본에 붙여 무엇이 채워지고 무엇이 비는지 센다(앱을 띄우지 않는다). */
+export * from './reference-probe.js'

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

@@ -1,3 +1,4 @@
+import type { ReferenceStep } from './reference-progress.js'
 import type { ReferenceMaster } from './reference-master.js'
 
 /*
@@ -102,6 +103,59 @@ export interface ControlResult {
   detail?: string
 }
 
+/**
+ * 한 흐름의 읽기 커서 — **어디까지 읽었나.**
+ *
+ * `since` 와 `seen` 이 **함께** 있어야 한다. 이어 읽기는 경계 시각을 겹쳐 읽고(`gte`), 그 겹침을
+ * `seen` 이 걸러 낸다. `gt` 로 좁히면 같은 밀리초의 다른 행이 사라진다 — 조용한 누락이다.
+ *
+ * `seen` 이 예상보다 커지면(한 시각에 몰린 행 수가 늘면) 그것은 원본 쪽 신호다. 어댑터가 그 크기를
+ * 말해야 한다 — 조용히 커지게 두면 이어 읽기가 막히는 순간까지 아무도 모른다.
+ */
+export interface LiveFeedCursor {
+  /** 그 흐름에서 마지막으로 본 시각(원본의 시각, ISO). */
+  since?: string
+  /** 그 시각에 이미 소비한 행 id — 겹쳐 읽은 것을 걸러 낸다. 저장되는 모양이므로 배열이다. */
+  seen: string[]
+}
+
+/**
+ * 재기동을 넘어 이어지는 읽기 상태 — 참조 계층이 소유하고 어댑터에 건넨다(§`openLiveFeed`).
+ *
+ * 흐름 열쇠는 **어댑터가 정한다**(`Record`). 계약이 이름을 닫으면 새 원본마다 계약을 고치게 된다.
+ */
+export interface LiveFeedContinuity {
+  /** 지난번에 어디까지 읽었나 — 없으면 첫 붙음이다(그때만 되돌아볼 날수로 창을 만든다). */
+  cursor?: { streams?: Record<string, LiveFeedCursor>; firstAttachedAt?: string }
+  /**
+   * 커서가 움직였다고 알린다 — 이 층이 저장한다.
+   *
+   * 어댑터가 **매 행마다 부르지 않는다**: 저장은 이 층의 몫이고, 잦으면 이 층이 눌린다. 흐름 하나가
+   * 한 묶음을 소비한 뒤 한 번이면 충분하다.
+   */
+  onCursor?: (cursor: { streams: Record<string, LiveFeedCursor>; firstAttachedAt?: string }) => void
+  /**
+   * **원본에 닿지 못했다** — 어댑터가 읽기 실패를 알린다(2026-08-23).
+   *
+   * ── 무엇이 조용했나 ─────────────────────────────────────────────────────────
+   * 실 원본이 끊겼을 때(접속 시간 초과) 트윈의 **조회 가능한 상태 어디에도** 그 사실이 없었다.
+   * `onRecords` 가 불리지 않으면 유입 장부에 아무 일도 일어나지 않고, `TwinReference.lastError` 는
+   * 마스터 동기·접속 시험에만 적힌다. 그래서 화면이 볼 수 있는 것은 「새 사실이 없다」뿐이었고,
+   * 그것은 **「원본이 조용하다」와 구별되지 않는다.**
+   *
+   * 어댑터는 로그로 말하고 있었다(재시도 경고). 그러나 **로그는 사람이 볼 때만 값이 있다** — 화면이
+   * 말하려면 상태에 있어야 한다. 이 통로가 그 자리다.
+   *
+   * ── 무엇을 알리고 무엇을 알리지 않나 ────────────────────────────────────────
+   * **재시도를 다 쓰고 그 주기를 포기했을 때** 부른다 — 재시도마다 부르면 한 번의 흔들림이 단절로 보인다.
+   * 흐름 여럿을 읽는 원본은 흐름 이름을 함께 준다(어느 표가 막혔나가 원인 찾기의 절반이다).
+   *
+   * **빈 읽기는 실패가 아니다** — 원본이 「새 것이 없다」고 답한 것은 닿았다는 뜻이므로 `onRecords([])`
+   * 로 알린다. 그 둘을 섞으면 조용한 원본이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
+   */
+  onReadFailure?: (info: { reason: string; stream?: string }) => void
+}
+
 export interface ReferenceAdapter {
   /** 레지스트리 키 (예: 'virtual' | 'sap-ewm' | 'custom-rest'). */
   type: string
@@ -112,9 +166,65 @@ export interface ReferenceAdapter {
   /** N 발견 — 사이트/공장 열거. 단일 소스는 길이 1 반환. */
   discoverSites(cfg: ConnectionConfig): Promise<SiteDescriptor[]>
   /** 사이트별 마스터(구조) — 기존 masterToTwin 이 소비. */
-  fetchMaster(cfg: ConnectionConfig, site: SiteDescriptor): Promise<ReferenceMaster>
-  /** (선택) 사이트별 실 이벤트 스트림 — 없으면 sim. onRecords 로 레코드 push, unsubscribe 반환. */
-  openLiveFeed?(cfg: ConnectionConfig, site: SiteDescriptor, onRecords: (records: unknown[]) => void): () => void
+  /**
+   * 이 어댑터가 마스터를 읽으며 **보낼 단계를 미리 선언한다** — 그것이 진행률의 분모다.
+   *
+   * 표준 낱말만 쓴다(`REFERENCE_STEPS`). 선언하지 않으면 화면은 퍼센트를 보이지 않고 단계 이름만
+   * 보인다 — **모르는 진행률을 지어내지 않는다.**
+   *
+   * 원본에 없는 자리는 선언하지 않는다. 그러면 「이 원본으로 채울 수 있는 만큼」이 곧 분모가 된다.
+   */
+  masterSteps?: readonly ReferenceStep[]
+
+  /**
+   * @param onStep 진행을 알리는 통로 — **선택이다.** 주지 않으면 예전과 같이 동작한다.
+   *
+   * 마스터 읽기는 원본에 여러 질의를 보내는 긴 작업이고(창고·자리·설비·공정·경로·품목·BOM), 화면은 그
+   * 사이에 아무것도 알 수 없었다. 어댑터만 자기 단계를 아므로 어댑터가 말해야 한다 — 호스트가 짐작하면
+   * 그것은 지어낸 진행률이다.
+   *
+   * `total` 은 **그 어댑터가 보낼 단계 수**다. 모르면 주지 않는다(화면이 퍼센트를 만들지 않는다).
+   */
+  fetchMaster(
+    cfg: ConnectionConfig,
+    site: SiteDescriptor,
+    onStep?: (step: { key: ReferenceStep; done: number; total?: number; detail?: string }) => void
+  ): Promise<ReferenceMaster>
+  /**
+   * (선택) 사이트별 실 이벤트 스트림 — 없으면 sim. onRecords 로 레코드 push, unsubscribe 반환.
+   *
+   * ── 네 번째 인자: **읽기 커서** (2026-08-23) ────────────────────────────────
+   *
+   * 왜 이 층이 커서를 드나: 커널이 그 갈림을 이미 적어 두었다(§`hydrateContinuity`) — 「원천이 **애초에
+   * 다시 말해 주지 않는 축**」은 재기동 연속성으로 이어받는다. **「우리가 어디까지 읽었나」가 정확히 그
+   * 성질이다.** 원본은 그것을 되풀어 주지 않는다.
+   *
+   * 커서가 없던 동안 어댑터는 붙을 때마다 `Date.now() − 되돌아볼 날수` 로 창을 새로 만들었다. 그래서
+   * **재기동마다 미러의 과거가 잘렸다** — 실측으로 작업 2,855 → 2,820(8시간 흐른 만큼). 미러가 아는
+   * 것이 「원본의 사실」이 아니라 「창의 함수」였다.
+   *
+   * 그런데 미러의 상태는 **원천으로 서야 한다**(같은 절: 「미러의 진실은 원천이다 … 심으면 떠난 물건이
+   * 되살아난다」). 그러니 저널을 접어 상태를 세우는 것으로 고칠 일이 아니다 — 그 선언의 **전제**가
+   * 「원천이 다시 말해 준다」이고, 창이 좁아지면 그 전제가 깨진다. 창을 고치는 것이 그 원칙을 지키는 길이다.
+   *
+   * ── 계약의 모양 ─────────────────────────────────────────────────────────────
+   *  · **흐름 열쇠는 어댑터가 정한다.** 원본마다 흐름 수와 뜻이 다르다(이 원본은 재고·오더·로트·투입 넷).
+   *    계약이 이름을 닫으면 새 원본마다 계약을 고치게 된다 — 원본의 스키마가 계약을 끌고 가는 그 모양이다.
+   *  · **저장되는 모양으로 넘긴다**(`seen` 은 배열). 이 층은 저장·복원만 하고 안을 해석하지 않는다.
+   *    `Set` 을 받으면 이 층이 직렬화를 알게 되고, 커서 모양이 바뀔 때 두 곳을 고친다.
+   *  · `firstAttachedAt` — **첫 창을 만든 시각.** 이후 재기동에서 바뀌지 않는다. 커널은 아는 구간의
+   *    상한만 안다(`nowTime` = 마지막으로 들은 시각). 이 값이 하한이고, 둘이 「이 트윈이 아는 구간」이다.
+   *    화면이 수를 보일 때 그 구간을 함께 말해야 한다 — 말하지 않으면 조용히 자르는 것이 된다.
+   *  · **커서가 없을 때만** 되돌아볼 날수를 쓴다. 그 순간이 `firstAttachedAt` 이다.
+   *
+   * 주지 않는 호출자와도 함께 선다(선택 인자) — 커서를 모르는 배포는 예전처럼 동작한다.
+   */
+  openLiveFeed?(
+    cfg: ConnectionConfig,
+    site: SiteDescriptor,
+    onRecords: (records: unknown[]) => void,
+    continuity?: LiveFeedContinuity
+  ): () => void
   /**
    * 이 원본이 **선언하는 능력** — 없으면 「구조만 준다」는 뜻이다(ADR-0029 §8).
    *
@@ -122,6 +232,28 @@ export interface ReferenceAdapter {
    * 구현이 없으면 그 능력은 **없는 것으로 읽는다**(선언만 있는 능력은 사용자에게 거짓말이 된다).
    */
   capabilities?: ReferenceCapability[]
+  /**
+   * 이 커넥터가 **무엇에 대고 확인됐나** — 능력과 다른 축이다(2026-08-23).
+   *
+   * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+   * `capabilities` 는 「무엇을 할 수 있다고 선언하나」이고, 이 자리는 **「그 선언이 무엇으로 확인됐나」**다.
+   * 둘이 갈리는 것이 지금 상태다: 등록된 커넥터 열넷 중 실 시스템에 붙어 본 것은 **하나**이고, 나머지는
+   * 목(mock)에 대고 만들었다. 그런데 화면의 커넥터 목록에 그 구분이 없어서 **목으로 확인한 것이 확인으로
+   * 보인다.**
+   *
+   * 그것은 이 저장소가 다른 자리에서 계속 거절하는 모양이다 — 「선언만 있는 능력은 사용자에게
+   * 거짓말이 된다」(§`capabilitiesOf`). 능력에 세운 그 규율을 근거에도 세운다.
+   *
+   * ── 왜 계약이고 배포 노트가 아닌가 ──────────────────────────────────────────
+   * 노트는 다음 사람이 보지 않는다. 계약에 있으면 새 커넥터가 그 값을 **빠뜨릴 수 없고**, 빠뜨리면
+   * `groundingOf` 가 `unknown` 으로 답해 화면이 그 사실을 말한다.
+   *
+   * ── 자동으로 알 수 없는 값이다 ──────────────────────────────────────────────
+   * 능력은 구현이 있는지 보면 알 수 있다. 「실 시스템에 붙여 봤나」는 **볼 수 없다** — 사람이 아는 사실이다.
+   * 그래서 이 선언은 낡을 수 있고, 그것을 막는 것이 `verifiedAgainst` 다: **무엇에 대고 확인했는지 적지
+   * 않으면 그 주장은 주장이 아니다**(`groundingOf` 가 `unknown` 으로 내린다).
+   */
+  grounding?: ReferenceGrounding
   /**
    * (선택) 구동 — 자극·속도·정지·초기화. **`capabilities` 에 `control` 을 선언한 원본만** 가진다.
    *
@@ -136,6 +268,59 @@ export interface ReferenceAdapter {
  * 선언만 있고 구현이 없으면 화면이 「할 수 있다」고 말한 뒤 아무 일도 일어나지 않는다. 반대로 구현이
  * 있는데 선언이 없으면 그 능력은 **의도적으로 닫아 둔 것**이므로 열지 않는다 — 선언이 권위다.
  */
+/**
+ * 근거 수준 — **무엇에 대고 확인했나.** 넷이고 닫혀 있다.
+ *
+ *   `synthetic`  실 시스템이 아니다 — 스스로 만들어 낸다(가상 원본·시뮬레이터). 한계가 아니라 성질이다.
+ *   `mock`       목·목 REST 에 대고만 확인했다. **실 시스템에 붙어 본 적이 없다.**
+ *   `instance`   실 시스템 **한 배포**에 붙여 확인했다. 그 배포의 성질과 제품의 성질을 아직 가르지 못했다.
+ *   `product`    실 시스템 **여러 배포**에 붙여 확인했다 — 그때 비로소 제품의 성질이라 말할 수 있다.
+ *
+ * `instance` 와 `product` 를 가르는 이유: 첫 실 연동에서 그 배포만의 성질이 넷 드러났고(관계 리솔버가
+ * 다른 테넌트의 행을 답한다 · 모르는 필터를 조용히 무시한다 · 지워진 품목의 BOM 이 남아 있다 ·
+ * 사실상 무한을 뜻하는 표식) **그것이 그 제품의 성질인지 그 인스턴스의 성질인지 아무도 모른다.**
+ * 두 번째 배포가 붙는 날 갈린다. 그 사실을 어휘가 담는다.
+ */
+export type ReferenceGroundingLevel = 'synthetic' | 'mock' | 'instance' | 'product'
+
+export interface ReferenceGrounding {
+  level: ReferenceGroundingLevel
+  /**
+   * **무엇에 대고 확인했나** — 사람이 읽는 한 줄(원본의 판·인스턴스·목의 이름).
+   *
+   * `instance`·`product` 를 주장하면서 이것이 비어 있으면 `groundingOf` 가 `unknown` 으로 내린다 —
+   * 가리키는 대상이 없는 주장은 주장이 아니고, 그런 주장은 낡아도 아무도 알 수 없다.
+   */
+  verifiedAgainst?: string
+}
+
+/**
+ * 이 커넥터의 근거 — **주장을 그대로 믿지 않는다**(`capabilitiesOf` 와 같은 규율).
+ *
+ * 능력은 구현이 있는지 보아 선언을 검증할 수 있다. 근거는 **볼 수 없다** — 사람이 아는 사실이다.
+ * 그래서 검증할 수 있는 것 하나만 검증한다: **실 시스템을 주장하면 무엇에 대고인지 말해야 한다.**
+ *
+ * 선언이 없으면 `unknown` 이다 — 「목이다」가 아니라 **「모른다」**다. 둘을 같게 두면 아직 선언하지 않은
+ * 새 커넥터가 목으로 낙인찍히고, 그것도 없는 사실이다.
+ */
+export function groundingOf(adapter: ReferenceAdapter | undefined): {
+  level: ReferenceGroundingLevel | 'unknown'
+  verifiedAgainst?: string
+  /** 주장이 내려갔으면 그 이유 — 화면이 그대로 옮긴다. */
+  downgraded?: string
+} {
+  const g = adapter?.grounding
+  if (!g?.level) return { level: 'unknown' }
+  const against = g.verifiedAgainst?.trim()
+  if ((g.level === 'instance' || g.level === 'product') && !against) {
+    return {
+      level: 'unknown',
+      downgraded: `claims "${g.level}" but does not say what it was verified against`
+    }
+  }
+  return { level: g.level, ...(against ? { verifiedAgainst: against } : {}) }
+}
+
 export function capabilitiesOf(adapter: ReferenceAdapter | undefined): ReferenceCapability[] {
   if (!adapter) return []
   const declared = new Set(adapter.capabilities ?? [])
@@ -158,6 +343,13 @@ export function listAdapterTypes(): string[] {
   return [...adapters.keys()]
 }
 /** 커넥터 메타데이터 목록(picker·연결 폼용). */
-export function listAdapters(): { type: string; meta?: AdapterMeta }[] {
-  return [...adapters.values()].map(a => ({ type: a.type, meta: a.meta }))
+/**
+ * 등록된 어댑터 목록 — **선언한 능력도 함께 낸다.**
+ *
+ * 예전에는 `{ type, meta }` 만 냈습니다. 그런데 소비처(어댑터 목록 질의)가 `capabilities` 를 함께
+ * 내보내고 있어 타입검사가 막혔고, 그 상태로는 개발 서버 빌드가 실패합니다. 능력은 이 목록을 읽는
+ * 화면이 「이 원본에 무엇을 요구할 수 있나」를 판단하는 근거이므로, 빼지 않고 여기서 함께 냅니다.
+ */
+export function listAdapters(): { type: string; meta?: AdapterMeta; capabilities?: ReferenceCapability[] }[] {
+  return [...adapters.values()].map(a => ({ type: a.type, meta: a.meta, capabilities: a.capabilities }))
 }