@vibexnpm/talkx 5.3.0 → 5.4.0

package/dist/index.d.ts

@@ -327,16 +327,20 @@ export interface RefreshSummaryOptions {
 export interface RefreshSummaryResult {
     /**
      * <ul>
-     *   <li>{@code 'STARTED'} — 요약 워커 시작됨({@code summaryUpdate} 대기).</li>
-     *   <li>{@code 'ALREADY_RUNNING'} — 방에서 요약이 진행 중(<b>다른</b> 포맷·언어일 수 있음). {@code format}/{@code language}
-     *       로 내 키인지 확인하고, {@code summaryUpdate} 가 내 키가 아니면 그때 다시 요청한다(무조건 재요청 금지 아님).</li>
-     *   <li>{@code 'NO_CHANGE'} — 새 대화 없음(알림 발생 안 함; 직전 실패가 있었다면 자동 복구됨).</li>
+     *   <li>{@code 'QUEUED'} — 방 단위 durable work item 에 저장·병합됐다. pod 실행 슬롯이 포화여도
+     *       요청은 버려지지 않으며, 최종 {@code READY|NO_CHANGE|NO_MESSAGES|FAILED} {@code summaryUpdate} 를 기다린다.</li>
      * </ul>
+     *
+     * <p>durable 저장 자체가 실패하면 성공 결과가 아니라 <b>HTTP 503</b>
+     * ({@code SUMMARY_REFRESH_UNAVAILABLE})으로 오며, {@link ChatClient.refreshSummary} 가 reject 한다.</p>
+     *
+     * <p>⚠️ <b>닫힌 union 이 아니다</b>: 서버가 값을 추가할 수 있으므로 분기에는 반드시 default 를 둔다.
+     * 모르는 값을 {@code QUEUED} 로 가정하지 말고 별도 상태 확인 UI를 표시한다.</p>
      */
-    status: 'STARTED' | 'ALREADY_RUNNING' | 'NO_CHANGE';
-    /** 이번 요청이 해소한 포맷({@link SummarizeFormat} 소문자). 방 단위 경합 식별용. */
+    status: 'QUEUED' | (string & {});
+    /** durable work item 에 병합한 포맷({@link SummarizeFormat} 소문자). */
     format?: string;
-    /** 이번 요청이 해소한 언어(소문자 BCP-47 / {@code 'OFF'}=원문). 방 단위 경합 식별용. */
+    /** durable work item 에 병합한 요청자 언어(소문자 BCP-47 / {@code 'OFF'}=원문). */
     language?: string;
 }
 
@@ -400,11 +404,15 @@ export interface RoomSummaryView {
      */
     language: string;
     /**
-     * 방 전체 요약 프로세스 상태 — {@code 'IDLE'}(대기) | {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(실패).
-     * <b>방 단위(키별 아님)</b>: 방은 한 번에 한 키만 요약하므로, 지금 다른 포맷·언어를 요약 중이어도 {@code 'RUNNING'} 이다.
-     * 특정 rollup 의 최신 여부는 {@code rollup.stale} 로 판단한다(rollup 자체는 완료된 데이터). 요약 이력이 없으면 null.
+     * 실행 상태 — {@code 'QUEUED'}(durable 대기) | {@code 'IDLE'}(유휴) |
+     * {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(선택 키 실패) |
+     * {@code 'NO_MESSAGES'}(선택 키에 요약할 대화 없음).
+     * 대기/실행은 방 단위이고 terminal 결과는 조회한 포맷×언어 키 기준이다. 특정 rollup 의 최신 여부는
+     * {@code rollup.stale} 로 판단한다. 요약 이력이 없어도 durable job 상태가 있으면 null이 아닐 수 있다.
+     * 닫힌 union이 아니므로 분기에는 default를 둔다.
      */
-    roomStatus: 'IDLE' | 'RUNNING' | 'FAILED' | null;
+    /** durable execution-plane 상태에서 합성되므로 재접속 뒤에도 복원된다. */
+    roomStatus: 'QUEUED' | 'IDLE' | 'RUNNING' | 'FAILED' | 'NO_MESSAGES' | (string & {}) | null;
     /** 요청/기본 포맷의 통합 요약본. 그 포맷×언어로 아직 요약 안 됐으면 null(availableFormats 로 같은 언어의 다른 포맷 확인). */
     rollup: RoomSummaryRollup | null;
     /** 이 방이 <b>이 언어로</b> 보유한 포맷 목록(short/timeline/… — 탭 렌더용). 타 언어는 포함하지 않는다. */
@@ -424,15 +432,18 @@ export interface RoomSummaryView {
 export interface SummaryUpdateEvent {
     roomId: string;
     /**
-     * {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) | {@code 'NO_CHANGE'}(변경 없음) |
+     * {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) |
+     * {@code 'NO_CHANGE'}(변경 없이 durable 작업 종결 → getSummary로 최종 동기화) |
+     * {@code 'NO_MESSAGES'}(선택 키에 요약할 대화 없음) |
      * {@code 'INVALIDATED'}(방 원문 삭제/편집으로 요약이 통째로 버려짐 → 화면을 비우고 필요 시 refreshSummary 로 재생성).
+     * 닫힌 union이 아니므로 모르는 값은 추측하지 말고 one-shot getSummary로 재동기화한다.
      */
-    status: 'READY' | 'NO_CHANGE' | 'FAILED' | 'INVALIDATED';
-    /** 완료/실패한 포맷. {@code READY}·{@code FAILED} 포함, {@code NO_CHANGE}·{@code INVALIDATED} 는 null. */
+    status: 'READY' | 'NO_CHANGE' | 'NO_MESSAGES' | 'FAILED' | 'INVALIDATED' | (string & {});
+    /** 완료 포맷. {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 포함, {@code INVALIDATED} 는 null. */
     format: string | null;
     /**
-     * fan-out 으로 한 번에 생성/최신화된 언어 목록(소문자 BCP-47 / {@code 'OFF'}). {@code READY}·{@code FAILED} 포함,
-     * 그 외 null. 각 사용자는 자기 언어가 이 목록에 있으면 {@code getSummary({ format, lang })} 로 읽는다(§S1).
+     * fan-out 으로 한 번에 처리한 언어 목록(소문자 BCP-47 / {@code 'OFF'}).
+     * {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 포함, {@code INVALIDATED} 만 null.
      */
     languages: string[] | null;
     /** 갱신 시각(epoch millis). {@code READY} 만 포함, 그 외 null. */