@things-factory/headless-twin 10.1.277 → 10.1.279

package/server/service/twin-ingest-window/twin-ingest-window-writer.ts

@@ -1,57 +0,0 @@
-import { twinWarn } from '../../engine/log.js'
-import { getRepository } from '@things-factory/shell'
-
-import { TwinEngine } from '../../engine/index.js'
-import { TwinIngestWindow } from './twin-ingest-window.js'
-
-/*
- * 닫힌 창을 표로 옮긴다 — **영속이 붙는 유일한 자리.**
- *
- * 커널 층(`engine/ingest-health.ts`)은 저장 계층을 모른다. 창이 닫힐 때 부를 곳을 엔진이 문으로 열어
- * 두었고(`onIngestWindowClosed`), 이 파일이 부팅에서 한 번 등록한다. 그래서 기록 경로가 갈리지 않는다.
- *
- * ── 실패를 삼키지 않는다 ────────────────────────────────────────────────────
- * 쓰기가 터져도 메모리 장부는 계속 굴러간다(`rollIngestWindow` 가 훅을 감싼다). 다만 **알리지 않고 넘기지는
- * 않는다** — 실패를 로그로 남긴다. 그러지 않으면 추이 표에 구멍이 생긴 이유를 나중에 알 수 없다.
- *
- * ── 왜 await 하지 않나 ──────────────────────────────────────────────────────
- * 이 훅은 인제스트 경로에서 불린다(라이브 피드의 콜백 안). 여기서 DB 를 기다리면 **유입이 DB 속도에
- * 묶인다** — 이 기능이 막으려던 부하가 그 모양으로 돌아온다. 그래서 띄워 보내고 결과만 로그로 받는다.
- */
-export function installIngestWindowWriter(): void {
-  TwinEngine.onIngestWindowClosed((at, closed) => {
-    const repo = getRepository(TwinIngestWindow)
-    const offered = closed.offered
-    repo
-      .save(
-        repo.create({
-          domain: { id: at.domainId } as any,
-          instanceId: at.instanceId,
-          openedAt: new Date(closed.startMs),
-          closedAt: new Date(closed.endMs),
-          offered,
-          rejected: closed.rejected,
-          undelivered: closed.undelivered,
-          /* 적힌 것도 같은 행에 — 창이 유입 없이 닫혔어도(시뮬) 이 두 수는 사실이다. */
-          journaledRows: closed.rows,
-          journalFlushes: closed.flushes,
-          /*
-           * 제시가 0 이면 비워 둔다 — 1 로 채우면 「전부 통과」로 읽힌다.
-           * 통과는 **트윈에 닿은** 것만이다: 버려진 것을 빼지 않으면 멈춘 트윈의 창이 100% 로 남는다.
-           */
-          ...(offered > 0
-            ? { acceptedRatio: round4((offered - closed.rejected - closed.undelivered) / offered) }
-            : {})
-        })
-      )
-      .catch(err =>
-        twinWarn(
-          `[twin-ingest-window] "${at.instanceId}" window not persisted (trend will have a gap here):`,
-          err?.message ?? err
-        )
-      )
-  })
-}
-
-/** 0.999 가 1 로 반올림되면 「전부 통과」로 읽힌다 — 자릿수를 넉넉히 준다(메모리 장부와 같은 규칙). */
-const round4 = (v: number) => Math.round(v * 10000) / 10000

package/server/service/twin-ingest-window/twin-ingest-window.ts

@@ -1,113 +0,0 @@
-import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'
-import { ObjectType, Field, ID, Int, Float } from 'type-graphql'
-
-import { Domain } from '@things-factory/shell'
-
-/*
- * 인제스트 창 하나 — **동기화 추이를 재기동 뒤에도 이어 보기 위한 행.**
- *
- * ── 왜 창마다이고 건마다가 아닌가 ───────────────────────────────────────────
- * 거부마다 행을 쓰면 라이브 계측 규모에서 초당 1만 행이고, 그 부하가 이벤트 루프로 돌아온다. 창마다면
- * 트윈 1,000개에 하루 14.4만 행(약 14MB)이다. 그래서 **닫힌 창 하나가 영속의 단위**다.
- *
- * 건마다 남기는 자리는 이미 따로 있다: 시나리오 경로가 `PayloadLog` 로 dead-letter 를 남긴다(배치성
- * 유입이라 건수가 감당된다). 이 표는 그것을 대신하지 않고 **추이**를 답한다.
- *
- * ── 왜 사유·표본은 여기 없나 ────────────────────────────────────────────────
- * 사유 문구는 길고 표본에는 **고객의 레코드 원문**이 들어 있다. 그것을 창마다 영속하면 표가 커지고
- * 고객 데이터가 오래 남는다. 사유와 표본은 메모리 장부가 답하고(최근 6시간), 이 표는 숫자만 든다.
- *
- * ── 고치지 않는다 ───────────────────────────────────────────────────────────
- * 닫힌 창은 지나간 사실이다. 그래서 `updatedAt`·`deletedAt` 을 두지 않는다(저널과 같은 규율).
- */
-@Entity()
-@Index('ix_twin_ingest_window_0', (e: TwinIngestWindow) => [e.domain, e.instanceId, e.closedAt], { unique: false })
-@ObjectType({
-  description:
-    'One closed ingest window for a twin: how many records were offered, accepted and rejected between two times. Written when a window closes (about every 10 minutes per twin) so the sync trend survives a restart and reaches further back than the in-memory ledger. Reasons and rejected-record samples are deliberately not stored here — they live in the in-memory ledger, which covers roughly the last 6 hours.'
-})
-export class TwinIngestWindow {
-  @PrimaryGeneratedColumn('uuid')
-  @Field(type => ID, { description: 'Unique identifier of the window record.' })
-  readonly id: string
-
-  @ManyToOne(type => Domain)
-  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
-  domain?: Domain
-
-  @RelationId((e: TwinIngestWindow) => e.domain)
-  domainId?: string
-
-  @Column()
-  @Field({ description: 'Twin runtime instance this window belongs to.' })
-  instanceId: string
-
-  @Column()
-  @Field({ description: 'When the window opened.' })
-  openedAt: Date
-
-  @Column()
-  @Field({ description: 'When the window closed. Windows close on the next ingest after the window length elapses, so a feed that stops leaves its last window open and unwritten.' })
-  closedAt: Date
-
-  @Column({ type: 'int' })
-  @Field(type => Int, { description: 'Records offered in this window, whether or not they were accepted.' })
-  offered: number
-
-  @Column({ type: 'int' })
-  @Field(type => Int, { description: 'Records the kernel refused in this window because they did not map — the fix is in the mapping.' })
-  rejected: number
-
-  /*
-   * 거부와 따로 센다 — **처방이 다르다.**
-   *
-   * 트윈이 라이브로 돌지 않으면 커널이 레코드를 버린다. 그것을 거부에 합치면 「매핑을 고쳐라」로 읽히고,
-   * 통과에 합치면 멈춘 트윈이 100% 로 보인다(실제로 그렇게 떴다). 그래서 제3의 수로 남긴다.
-   */
-  @Column({ type: 'int', default: 0 })
-  @Field(type => Int, {
-    description:
-      'Records that mapped fine but never reached the twin, because the twin was not running live while the feed kept delivering. Distinct from rejected: the fix here is to start the twin or disconnect the feed, not to change the mapping. Offered minus rejected minus undelivered is what actually reached the twin.'
-  })
-  undelivered: number
-
-  /*
-   * 통과율을 **함께 적는다.** 읽는 쪽에서 나누게 하면 소비처마다 반올림이 갈리고(0.999 를 1 로 쓰는
-   * 곳이 생긴다), 제시가 0 인 창에서 0으로 나누는 실수가 각자 생긴다. 제시가 0 이면 **비어 둔다** —
-   * 1 로 채우면 「전부 통과」로 읽힌다.
-   */
-  @Column({ type: 'float', nullable: true })
-  @Field(type => Float, {
-    nullable: true,
-    description:
-      'Share of offered records that reached the twin (0–1), rounded to four places. Null when nothing was offered in this window — an empty window is not a perfect one, and writing 1 there would read as "everything passed".'
-  })
-  acceptedRatio?: number
-
-  /*
-   * ── 적힌 것도 같은 창에 든다 ────────────────────────────────────────────────
-   * 유입과 **다른 축**이다. 시뮬 트윈은 받는 것 없이 자기가 낸 사실을 적으므로 `offered` 가 0 이고
-   * `journaledRows` 는 0 이 아니다. 이 칸이 없으면 도는 트윈 대부분이 시뮬인 서버의 활동이 어느 추이에도
-   * 남지 않는다(계기는 지금만 답하고 재기동에 0 으로 돌아간다).
-   *
-   * 두 수를 따로 세는 이유: 2026-08-20 에 고친 것이 **행당 왕복**이다(델타마다 한 번 → 창당 한 번).
-   * 행만 세면 그 개선도, 되돌아가는 것도 보이지 않는다.
-   */
-  @Column({ type: 'int', default: 0 })
-  @Field(type => Int, {
-    description:
-      'Journal rows written for this twin during this window. This is a different axis from ingest: a twin driven by a simulator source receives nothing (offered = 0) yet writes what it produces, so without this column its activity appears in no trend at all.'
-  })
-  journaledRows: number
-
-  @Column({ type: 'int', default: 0 })
-  @Field(type => Int, {
-    description:
-      'Number of journal write round-trips (flushes) behind those rows. Counted separately from the rows themselves so that a regression back to per-delta writes — the defect fixed on 2026-08-20, where each kernel delta cost one insert — is visible as rows-per-flush falling back towards 1.'
-  })
-  journalFlushes: number
-
-  @CreateDateColumn()
-  @Field({ nullable: true, description: 'When this record was written.' })
-  createdAt?: Date
-}

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

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

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

@@ -1,199 +0,0 @@
-import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
-import { ObjectType, Field, ID } from 'type-graphql'
-
-import { Domain, ScalarObject } from '@things-factory/shell'
-import { User } from '@things-factory/auth-base'
-import { modelColumnTransformer } from '../../engine/model-vocabulary.js'
-
-/*
- * TwinInstance — 트윈 인스턴스 레지스트리(재부팅 복구의 앵커).
- * 복구(DB→replay)는 model(마스터 청사진)가 있어야 이벤트를 상태로 다시 계산할 수 있다 → model·kind 를 영속.
- * 이벤트(TwinEvent)와 달리 가변(status 갱신) — 인스턴스의 "현재 등록 상태".
- * model 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통).
- * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)
- */
-@Entity()
-@Index('ix_twin_instance_0', (e: TwinInstance) => [e.domain, e.instanceId], { unique: true })
-@Index('ix_twin_instance_1', (e: TwinInstance) => [e.domain, e.spaceId]) // 공간→인스턴스 1급 질의(공간 중심 존재론)
-@ObjectType({ description: 'Registry of a hosted twin runtime instance — anchors reboot recovery (model + kind).' })
-export class TwinInstance {
-  @PrimaryGeneratedColumn('uuid')
-  @Field(type => ID, { description: 'Unique identifier of the registry record.' })
-  readonly id: string
-
-  @ManyToOne(type => Domain)
-  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
-  domain?: Domain
-
-  @RelationId((e: TwinInstance) => e.domain)
-  domainId?: string
-
-  @Column()
-  @Field({ description: 'Twin runtime instance id (unique within a domain).' })
-  instanceId: string
-
-  /**
-   * **사람이 부르는 이름** — 업무키(`instanceId`)와 나란히 두는 표시명(프레임워크 엔티티 규약).
-   *
-   * ── 왜 업무키와 이름을 나눠 두나 ─────────────────────────────────────────────
-   * `instanceId` 는 URL·저널·구독이 전부 쓰는 **계약**이라 바꿀 수 없다. 반대로 이름은 바뀌고,
-   * 중복되고(사이트 둘에 "도장" 이 있는 것이 정상), 언어마다 다르다. 둘을 한 컬럼에 담으면 개명이
-   * 곧 다른 트윈이 되고 재동기가 끊긴다 — 그래서 나눈다(이 저장소에서 식별자가 밖에서 오는 것은
-   * 전부 이 규약을 쓴다: `spaceId`·`locationId`·`equipmentId`·`operationKey`).
-   *
-   * 나눴으면 **이름을 반드시 함께 둬야 한다.** 이 자리가 없던 동안 사이트 이름은 model 안에만 있어서
-   * 목록이 `crew-two` 만 보였다 — 나누기만 하고 절반을 빼먹으면 화면에는 id 만 남는다.
-   *
-   * 원본이 이름을 말하지 않으면 비운다(id 를 베끼지 않는다).
-   */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Human name of this twin (the site name from its master). Empty when the source does not name it — never copied from instanceId.' })
-  name?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Longer description when the source provides one.' })
-  description?: string
-
-  /* 어느 도메인 커널이 이 트윈을 운영하는가. 커널 없는 트윈은 없으므로 비어 있을 수 없다
-     (`TwinEngine.start`·`register` 모두 필수 인자로 받는다). */
-  @Column()
-  @Field({ description: 'Domain kernel kind: wms | yms | mes.' })
-  kind: string
-
-  /*
-   * **재기동 정책** — 이 트윈은 다시 세워질 때 자기 과거를 어떻게 대하나(ADR-0029 §2).
-   *
-   *   'resync' = 외부 실물에서 다시 읽는다(원본이 진실이므로 우리 과거를 이어 붙이지 않는다 → startLive).
-   *   'resume' = 저널을 이어 세운다(이 트윈이 낳은 타임라인이 곧 사실이다).
-   *   'reset'  = 저널을 비우고 씨앗부터 다시 돌린다(재현 가능한 실험 — 백지 시작이 선언된 거동이다).
-   *
-   * ── 왜 트윈에 남았나 (옛 이름 `realityMode`) ────────────────────────────────
-   * 「현실이 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이다(`TwinReference.adapterType`) —
-   * 트윈은 한 종류이고 언제나 원본을 반영한다. 그런데 코드가 이 축으로 실제로 가른 것은 **재기동 거동
-   * 하나**였고, 그것은 원본의 성질이 아니라 **트윈과 자기 과거의 관계**다: 같은 시뮬레이터 원본을 보는 두
-   * 트윈이 하나는 이어가고 하나는 매번 처음부터 재현할 수 있다. 그래서 축은 남고 이름만 바뀌었다.
-   *
-   * **비어 있을 수 없고, 기본값도 없다.** 예전에는 미선언이 알리지 않고 `sim-experiment`(=저널 초기화)로
-   * 떨어졌다 — 값이 하나 어긋나는 순간 이력을 지우는 길이다. 이제 읽는 쪽이 **오류를 낸다**
-   * (`engine/restart-policy.ts`). 선언은 프로비저닝하는 쪽의 몫이다.
-   */
-  @Column()
-  @Field({ description: "Restart policy: 'resync' (read again from the external source) | 'resume' (continue this twin's own journal) | 'reset' (wipe and replay from the seed). No default — an unspecified policy is refused." })
-  restartPolicy: string
-
-  /* 읽을 때 어휘 세대를 흡수한다(`nodes`/`movers`/`equipmentList` → `locations`/`equipment`).  (vocabulary-guard: allow — 세대 이름 없이는 설명할 수 없다.)
-     자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠지고, 빠진 것은 오류가 아니라 **빈 공장**이라
-     들어온 것이 없다(2026-08-06: 모델러 엔티티 목록이 통째로 비었다). 상세 `engine/model-vocabulary.ts`. */
-  @Column({ type: 'simple-json', nullable: true, transformer: modelColumnTransformer })
-  @Field(type => ScalarObject, { nullable: true, description: 'TwinModelDef blueprint (locations/equipment) required to replay events into state. Older stored boards used nodes/movers/equipmentList; they are normalised on read so consumers see one vocabulary.' }) // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)
-  model?: any
-
-  /*
-   * 로컬 선언 겹 — **구조는 원천이, 수는 우리가.**
-   *
-   * 요금 단가·계약 정보·축전지 충전율처럼 원 시스템이 모르는 값을 넣는 자리다. `model` 에 직접 쓰지
-   * 않는 이유는 그것이 **원천의 사본**이기 때문이다: 다시 읽기가 사본을 새로 그리면 직접 쓴 값은 알리지 않고
-   * 사라진다(요금이 사라지면 금액도 사라지고, 사용자는 이유를 알 수 없다).
-   *
-   * 그래서 여기 남기고, 모델을 그릴 때마다 그 위에 얹는다(`engine/local-declarations`). 얹힌 값에는
-   * `source: 'local'` 이 붙는다 — 커널 계약의 `PropertySource` 축(`reference` ↔ `local`)이고, 「밖에서
-   * 참조해 온 값이냐, 이 안에서 정한 값이냐」에 답한다.
-   *
-   * **이름에 장소 낱말을 쓰지 않는다**(옛 이름 `siteDeclarations`): 이 코드에서 `site` 는 **외부
-   * 시스템이 부르는 사업장**이고(SAP `P3`·Oracle `W01` 이 같은 현장), 여기 담기는 것은 그 외부 시스템이
-   * **모르는** 값이다 — 이름이 내용과 정반대였다. `space` 도 아니다: 그것은 「어디」에 답하고 이 축은
-   * 「누가 말했나」에 답한다.
-   */
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: "Locally-declared values layered on top of the reference-derived model (tariff, contract, state of charge) — values whose authority sits here, not in the source system. Kept apart from `model` so a resync cannot silently drop them." })
-  localDeclarations?: any
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Owning space id (co-location anchor). Promoted from model.spaceId — first-class "space → its twins" query (space-centered ontology).' })
-  spaceId?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Owning area id within the space (optional scope). Promoted from model.areaId.' })
-  areaId?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Lifecycle status: running | stopped.' })
-  status?: string
-
-  /*
-   * purpose — 이 인스턴스가 운영 트윈인지, 격리된 벤치 사본인지 1급 선언(이름 접두사가 아니라 속성으로 구별).
-   * 'bench' 는 규모/부하 실험용 격리 사본 — 목록·정리·안전 가드가 이 속성을 키로 동작(운영 트윈 무오염 보장).
-   *
-   * **비어 있을 수 없다.** 프로비저닝이 `register` 에서 'operational' 로 각인하고, 벤치 사본만
-   * `setPurpose` 로 뒤집는다. 예전에는 비워 둔 채 읽는 쪽에서 메웠는데, 그러면 "운영이라고 선언된 것"
-   * 과 "아무도 말하지 않은 것" 이 같은 값으로 보여서 벤치 격리가 추측에 기대게 된다.
-   */
-  @Column()
-  @Field({ description: "Instance purpose: 'operational' (real twin) | 'bench' (isolated copy for scale/load experiments)." })
-  purpose: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'For a bench copy: the source spaceId it was copied from (provenance).' })
-  copyOf?: string
-
-  /**
-   * **이 트윈을 다시 읽는 방법** — 어떤 원본에서 나왔나(`MasterOrigin`).
-   *
-   * 트윈은 원본을 비출 뿐이므로(ADR-0028) 원본이 달라지면 다시 읽어야 한다. 그런데 이 자리가 없던
-   * 동안 트윈은 **자기가 무엇에서 나왔는지 몰랐다** — 어댑터로 들어온 트윈은 `TwinReference` 행이
-   * 있었지만 템플릿으로 세운 트윈에는 아무 표식도 없었고, 그래서 첫날의 모습에 영원히 머무는
-   * 트윈이 만들어졌다. 원천이 무엇이든 여기 한 자리에 남긴다.
-   *
-   * **비어 있을 수 있다** — 이 자리가 생기기 전에 만들어진 트윈이 그렇다. 그때는 "다시 읽을 수
-   * 없다" 가 사실이므로 화면이 그대로 말한다(짐작해 채우지 않는다).
-   */
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, {
-    nullable: true,
-    description:
-      "How this twin's master can be produced again — {kind:'reference', source} or {kind:'template', templateId, params}. Absent means this twin cannot be re-read from its source."
-  })
-  origin?: any
-
-  /*
-   * `revision` 컬럼은 **없앴다**(2026-08-08).
-   *
-   * `ADR-0015` 가 "정의만 있고 write 안 됨 — 프로비저닝에서 최신 저널 revision 을 반영하도록
-   * 채운다" 고 적어 두었는데, 채우지 않는 편이 맞다. 저널의 최신 번호는 **저널이 아는 사실**이고
-   * (`TwinEngine.list` 가 `MAX(revision)` 으로 낸다), 여기 복제하면 **같은 사실의 집이 둘**이 된다.
-   * 이 세션에만 그 부류를 셋 겪었다(`model.operations` 두 집 · `materials` 두 집 · tenantId 중복).
-   *
-   * 복제한 값은 반드시 어긋난다 — 저널은 틱마다 늘고 이 컬럼은 저장할 때만 갱신되므로, 화면이
-   * 어느 쪽을 읽느냐로 다른 숫자가 나온다. 그 들어온 것이 없는 어긋남을 만들 이유가 없다.
-   */
-
-  @CreateDateColumn()
-  @Field({ nullable: true, description: 'Timestamp when the instance was first registered.' })
-  createdAt?: Date
-
-  @UpdateDateColumn()
-  @Field({ nullable: true, description: 'Timestamp when the instance registry row was last updated.' })
-  updatedAt?: Date
-
-  /*
-   * 누가 만들고 누가 고쳤나 — **이 행은 사람이 만든다**(프로비저닝은 사용자 행위)이므로 규약의
-   * 풀세트를 갖는다. 투영 행(자리·설비·공정)은 반대로 인제스트가 그린 것이라 저자가 사람이 아니고,
-   * 그 저자는 `sourceRef`+`ingestedAt` 이 이미 말한다 — 그래서 그쪽에는 두지 않는다.
-   *
-   * 비어 있을 수 있다: 부팅 자동 프로비저닝처럼 **사람이 없는 경로**로 만들어진 행이 그렇다.
-   * 그때 아무 사용자를 적어 넣으면 감사 기록이 거짓이 된다.
-   */
-  @ManyToOne(type => User, { nullable: true })
-  @Field(type => User, { nullable: true, description: 'The user who first provisioned this twin. Empty when it was created by a system path (boot provisioning).' })
-  creator?: User
-
-  @RelationId((e: TwinInstance) => e.creator)
-  creatorId?: string
-
-  @ManyToOne(type => User, { nullable: true })
-  @Field(type => User, { nullable: true, description: 'The user who last changed this twin registry row.' })
-  updater?: User
-
-  @RelationId((e: TwinInstance) => e.updater)
-  updaterId?: string
-}

package/server/service/twin-journal/event-type-split-shape.ts

@@ -1,112 +0,0 @@
-/*
- * **이 물음이 「여러 종류를 시각순으로」인가** — 순수 판단만 여기 둔다.
- *
- * 데이터베이스를 부르지 않는다. 그래서 시험이 이 파일을 그대로 부를 수 있다(데코레이터가 없다).
- * 판단이 조회 코드 안에 섞여 있으면 그 판단만 확인할 방법이 없고, 그러면 「어떤 물음이 나눠 묻는
- * 갈래로 가는가」가 아무도 읽지 못하는 규칙이 된다.
- *
- * 실측 근거와 고침의 뜻은 `event-type-split.ts` 머리에 있다.
- */
-import { absoluteTime } from '../../engine/read-time.js'
-
-/** 질의를 몇 개까지 나눌까 — 대상 × 종류. 이 이상이면 나누는 것이 손해다. */
-export const MAX_SPLIT = 24
-
-/** 종류 목록의 상한 — 이보다 많으면 「이 종류만」이 아니라 사실상 전체다. */
-const MAX_TYPES = 12
-
-export interface SplitShape {
-  eventTypes: string[]
-  /**
-   * 공정 단계 하나로 좁힌 경우 — 그 값을 갈래마다 함께 건다.
-   *
-   * 이 필터를 만나면 갈래를 포기하던 것을 고쳤다(2026-08-29). 원장은 종류를 담아 묻고 그 위에 단계
-   * 칩을 겹치는데, 칩을 고른 순간 예전 경로로 떨어져 **고르지 않은 쪽이 더 빨랐다.**
-   *
-   * 단계 컬럼에는 색인이 없다. 그래도 느려지지 않는다 — 종류 정확일치가 색인으로 시각 순서까지 주고,
-   * 단계는 그 안에서 행마다 확인하는 조건이다(걷는 행이 그 종류의 것으로 이미 좁혀져 있다).
-   */
-  bizStep?: string
-  untilTime?: Date
-  fromTime?: Date
-}
-
-/**
- * 이 물음이 「여러 종류를 시각순으로」인가 — 아니면 `null`.
- *
- * 받는 모양
- *   `eventType` 을 `in` 으로 · 시각 상한이나 구간 · 시각 내림차순 정렬
- *
- * 보내는 모양(일반 경로로)
- *   자유 검색어 · 그 밖의 필터(축·상관 식별자·업무 단계) · 그 밖의 정렬이나 연산자
- */
-export function splitShape(params: any, sortings: any[]): SplitShape | null {
-  const filters: any[] = Array.isArray(params?.filters) ? params.filters : []
-  if (typeof params?.search === 'string' && params.search.trim()) return null
-  if (sortings.length !== 1 || sortings[0]?.name !== 'eventTime' || sortings[0]?.desc !== true) return null
-
-  let eventTypes: string[] | undefined
-  let untilTime: Date | undefined
-  let fromTime: Date | undefined
-  let bizStep: string | undefined
-  for (const f of filters) {
-    if (f?.name === 'eventType') {
-      if (f.operator !== 'in' || !Array.isArray(f.value)) return null
-      const types: string[] = f.value.map((v: unknown) => String(v ?? '').trim()).filter((t: string) => !!t)
-      /* 하나면 나눌 것이 없다(이미 정확일치라 색인을 탄다). 너무 많으면 사실상 전체다. */
-      if (types.length < 2 || types.length > MAX_TYPES) return null
-      if (eventTypes) return null
-      eventTypes = [...new Set(types)]
-    } else if (f?.name === 'bizStep') {
-      /* 하나로 좁힌 경우만 받는다 — 여러 값이면 종류 × 단계로 갈래가 곱해진다. */
-      if (f.operator !== 'eq') return null
-      const v = String(f.value ?? '').trim()
-      if (!v) return null
-      if (bizStep) return null
-      bizStep = v
-    } else if (f?.name === 'eventTime') {
-      if (f.operator === 'lte' || f.operator === 'lt') {
-        untilTime = absoluteTime(f.value) ?? undefined
-        if (!untilTime) return null
-      } else if (f.operator === 'between' && Array.isArray(f.value)) {
-        fromTime = absoluteTime(f.value[0]) ?? undefined
-        untilTime = absoluteTime(f.value[1]) ?? undefined
-        if (!fromTime || !untilTime) return null
-      } else return null
-    } else return null
-  }
-  return eventTypes ? { eventTypes, untilTime, fromTime, bizStep } : null
-}
-
-/**
- * **나눠 물은 갈래들을 합쳐 앞에서 `limit` 개** — 이 규율이 정확성의 근거다.
- *
- * ── 왜 갈래마다 `limit` 까지 받아야 하나 ────────────────────────────────────
- * 갈래마다 `limit` 개를 받아 합치면, 합친 것의 앞 `limit` 개는 **전체에서도** 앞 `limit` 개다.
- * 어떤 갈래에서 빠진 행은 그 갈래의 `limit` 번째보다 뒤이고, 우리는 전체에서 `limit` 개만 취하므로
- * 그 행이 이 페이지에 들어올 수 없다.
- *
- * 갈래마다 **더 적게** 받으면 그 성질이 깨진다. 한 갈래가 앞을 다 차지하는 경우
- * (종류 A 의 마지막이 종류 B 의 첫째보다 앞선다) 그 갈래에서 못 받은 것이 빠지고, 결과는 구간의
- * 앞부분만 계산한 것이 된다 — 그런데 화면은 「일부만 읽었다」고만 말하고 어느 부분인지는 말하지 못한다.
- * (2026-08-28 · UX 레인이 미리 짚어 준 함정이다.)
- *
- * 그래서 이 함수는 **`limit` 미만으로 받은 갈래가 있으면 그것을 말한다** — 부르는 쪽이 그 상태로
- * 답하지 않게.
- */
-export function mergeStreams<T>(
-  streams: readonly T[][],
-  limit: number,
-  /** 앞에 와야 하는 것이 음수 — `Array.prototype.sort` 와 같은 규약. */
-  compare: (a: T, b: T) => number
-): { items: T[]; capped: boolean; underfilled: boolean } {
-  const underfilled = streams.some(s => s.length > limit)
-  const merged = streams.flat().sort(compare)
-  return {
-    items: merged.slice(0, limit),
-    /* 합친 것이 상한을 넘었으면 더 있었다는 뜻이다 — 잘랐다는 사실을 부르는 쪽이 말해야 한다. */
-    capped: merged.length > limit || streams.some(s => s.length >= limit),
-    /* 갈래가 상한보다 많이 받아 왔다 — 있을 수 없는 일이므로 부르는 쪽이 알아야 한다. */
-    underfilled
-  }
-}

package/server/service/twin-journal/event-type-split.ts

@@ -1,144 +0,0 @@
-import { getRepository } from '@things-factory/shell'
-
-import { TwinEvent } from '../twin-event/twin-event.js'
-import { absoluteTime } from '../../engine/read-time.js'
-import { MAX_SPLIT, type SplitShape } from './event-type-split-shape.js'
-
-/*
- * **여러 종류를 시각순으로 — 종류를 하나씩 나눠 묻는다** (2026-08-28 실측).
- *
- * ── 무엇이 느렸나 ───────────────────────────────────────────────────────────
- * 에너지 원장은 「이 여덟 종류를 시각 내림차순으로 50건」을 묻는다. 그 모양에서 sqlite 는 종류 색인을
- * **버린다**:
- *
- *   종류 IN + 시각순     SEARCH USING INDEX ix_twin_event_1 (domain, instance)   37.181초 · 결과 0건
- *   같은 조건 · 정렬 없음  SEARCH USING INDEX ix_twin_event_7 (…, event_type=?)     0.003초
- *   종류 하나 + 시각순    SEARCH USING INDEX ix_twin_event_7 (…, event_type=?)     0.003초
- *
- * 정렬을 붙이는 순간 여러 종류의 순서를 합칠 방법이 없어, 시각 색인으로 337만 행을 걸으며 행마다
- * 종류를 확인한다. 승화푸드에 에너지 사건은 0건이다 — **없는 것을 찾느라 37초**를 쓴다.
- *
- * 360 이력이 64초였던 것과 같은 부류다: **거르는 축과 정렬 축이 어긋난다.**
- *
- * ── 고침 ────────────────────────────────────────────────────────────────────
- * 종류를 **정확일치로 하나씩** 물으면 색인이 시각 순서까지 그대로 준다(정렬이 사라진다). 여덟 종류면
- * 질의 여덟 개이고 각 0.003초다. 받은 것을 시각순으로 합쳐 한 페이지를 만든다.
- *
- * 새 색인도, 새 테이블도 필요 없다 — 있는 색인을 쓰게 하는 것이 전부다.
- *
- * ── 좁게 잡는다 ─────────────────────────────────────────────────────────────
- * 이 모양이 아닌 물음은 답하지 않고(`null`) 저널의 일반 경로로 보낸다. 억지로 답하면 목록이 알리지
- * 않고 달라진다.
- *
- * ── ★ **이 갈래를 걷을 조건** ────────────────────────────────────────────────
- * 앱에서 종류를 여러 값으로 보내는 곳은 **에너지 원장 한 곳뿐**이다(2026-08-28 확인). 그 화면이
- * 종류를 하나씩 고르는 모양으로 바뀌면 이 갈래를 부르는 데가 없어진다 — 그때 **지운다.**
- *
- * 부르는 데가 없는 갈래를 들고 있으면, 그것이 무언가를 받쳐 주는 것처럼 보이면서 실제로는 아무것도
- * 하지 않는다. 지금 살려 두는 이유는 하나다: 실 고객 트윈에서 37초 질의가 돌고 있고 화면 수정은
- * 다른 레인의 일이다.
- */
-
-export interface SplitPage {
-  items: TwinEvent[]
-  nextCursor?: string
-}
-
-/**
- * 나눠 묻고 합쳐 한 페이지 — 답할 수 없으면 `null`.
- *
- * 이어 읽기 지점은 **모든 갈래에 같이** 건다. 그래야 합친 결과가 커서 아래에서만 나온다 — 갈래마다
- * 다르게 걸면 어떤 종류는 이미 지나간 구간을 다시 낸다.
- */
-export async function eventTypeSplitPage(
-  domainId: string,
-  instanceIds: string[],
-  shape: SplitShape,
-  limit: number,
-  /** 동시각을 가리는 축 — 트윈 하나면 `revision`, 여럿이면 기본키(§`cursorTiebreak`). */
-  tiebreak: 'revision' | 'id',
-  after?: string
-): Promise<SplitPage | null> {
-  const pairs = instanceIds.length * shape.eventTypes.length
-  if (!pairs || pairs > MAX_SPLIT) return null
-
-  let cursor: { at: Date; tie: string | number } | null = null
-  if (after) {
-    cursor = decodeCursorPair(after)
-    if (!cursor) return null
-  }
-
-  const rows: TwinEvent[][] = []
-  for (const instanceId of instanceIds) {
-    for (const eventType of shape.eventTypes) {
-      const qb = getRepository(TwinEvent)
-        .createQueryBuilder('e')
-        .where('e.domain = :domainId', { domainId })
-        .andWhere('e.instanceId = :instanceId', { instanceId })
-        /* **정확일치**가 요점이다 — 그래야 색인이 시각 순서까지 준다(§ 위 실측). */
-        .andWhere('e.eventType = :eventType', { eventType })
-      /* 단계는 색인이 아니라 행 조건이다 — 종류 정확일치가 이미 걷는 범위를 좁혀 놓았다. */
-      if (shape.bizStep) qb.andWhere('e.bizStep = :bizStep', { bizStep: shape.bizStep })
-      if (shape.fromTime) qb.andWhere('e.eventTime >= :fromTime', { fromTime: shape.fromTime })
-      if (shape.untilTime) qb.andWhere('e.eventTime <= :untilTime', { untilTime: shape.untilTime })
-      if (cursor) {
-        qb.andWhere(`(e.eventTime < :curAt OR (e.eventTime = :curAt AND e.${tiebreak} < :curTie))`, {
-          curAt: cursor.at,
-          curTie: cursor.tie
-        })
-      }
-      const page = await qb
-        .orderBy('e.eventTime', 'DESC')
-        .addOrderBy(`e.${tiebreak}`, 'DESC')
-        .limit(limit)
-        .getMany()
-        .catch(() => null)
-      /* 한 갈래라도 못 읽으면 합친 결과가 반쪽이다 — 반쪽을 전부인 것처럼 내지 않는다. */
-      if (!page) return null
-      rows.push(page)
-    }
-  }
-
-  /*
-   * 합친다. 갈래마다 `limit` 까지 받았으므로, 합쳐서 앞의 `limit` 개는 **전체에서도** 앞의 `limit` 개다
-   * (각 갈래가 자기 안에서 정렬돼 있고 그보다 앞선 것을 빠뜨릴 수 없다).
-   */
-  const merged = rows
-    .flat()
-    .sort((a: any, b: any) => {
-      /* `getMany` 는 엔티티를 주므로 시각이 이미 날짜다 — 감싸면 드라이버 값을 손으로 읽는 모양이 된다. */
-      const at = (b.eventTime as Date).getTime() - (a.eventTime as Date).getTime()
-      if (at !== 0) return at
-      const x = a[tiebreak]
-      const y = b[tiebreak]
-      return x === y ? 0 : x < y ? 1 : -1
-    })
-    .slice(0, limit)
-
-  const last: any = merged[merged.length - 1]
-  const nextCursor =
-    merged.length === limit && last?.eventTime instanceof Date && last[tiebreak] !== undefined
-      ? encodeCursorPair(last.eventTime, last[tiebreak])
-      : undefined
-
-  return { items: merged, nextCursor }
-}
-
-/** 저널 경로와 같은 커서 — `[eventTime, 동시각 축]`(§`buildNextCursor`). */
-function encodeCursorPair(at: Date, tie: string | number): string {
-  return Buffer.from(JSON.stringify([at, tie]), 'utf8').toString('base64url')
-}
-
-function decodeCursorPair(cursor: string): { at: Date; tie: string | number } | null {
-  let values: unknown
-  try {
-    values = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'))
-  } catch {
-    return null
-  }
-  if (!Array.isArray(values) || values.length !== 2) return null
-  const at = absoluteTime(values[0])
-  const tie = values[1]
-  if (!at || (typeof tie !== 'string' && typeof tie !== 'number')) return null
-  return { at, tie }
-}

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

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

package/server/service/twin-journal/journal-order.ts

@@ -1,20 +0,0 @@
-/**
- * 지난 기록 조회의 정렬 축 — **부르는 쪽이 무엇으로 물었는지에 맞춘다.**
- *
- * 리졸버 안에 두면 이 규칙을 확인할 방법이 소스를 글자로 전수 조회하는 것뿐이다. 규칙 자체를 부를 수 있게
- * 밖으로 뺀다(`test/journal-order-axis.test.ts`).
- */
-export function journalOrder(q: {
-  untilTime?: string | null
-  fromTime?: string | null
-  fromRevision?: number | null
-  toRevision?: number | null
-}): {
-  eventTime?: 'DESC'
-  revision: 'DESC'
-} {
-  /* `revision` 으로 물었으면 그 순서가 물음의 답이다. 거르는 축과 정렬 축을 맞추는 규칙과도 같다. */
-  const byTime = q.untilTime != null || q.fromTime != null
-  if (!byTime && (q.fromRevision != null || q.toRevision != null)) return { revision: 'DESC' }
-  return { eventTime: 'DESC', revision: 'DESC' }
-}