@flamingo-stack/openframe-frontend-core 0.0.706-snapshot.20261006181108 → 0.0.706

package/src/chat-protocol/nats-decoder.ts

@@ -20,7 +20,7 @@ import { MESSAGE_TYPE } from '../components/chat/types/message.types';
 import type { AskOptionData } from '../components/chat/types/message.types';
 import { ESCALATION_STATE, escalationResolvedStatus } from './events';
 import type { ApprovalToolCall, ChatStreamEvent } from './events';
-import { attachmentsEvent, sourceMetadataEvent } from './source-metadata';
+import { sourceMetadataEvent } from './source-metadata';
 import { isRecord } from './wire-narrow';
 
 /** Minimal structural view of a NATS chunk (see `ChunkData` in
@@ -122,15 +122,13 @@ export function decodeNatsChunk(chunk: unknown): ChatStreamEvent | null {
       }
       return null;
 
-    // The chunk arrives BEFORE or between the answer's text deltas, so the
-    // reducer — not this decoder — owns attaching it to the right turn.
-    case MESSAGE_TYPE.ATTACHMENTS: {
-      const event = attachmentsEvent(data);
-      return event ? { ...event, ...seq } : null;
-    }
-
-    // The envelope `ATTACHMENTS` replaced (see `MESSAGE_TYPE.GUIDE`).
-    case MESSAGE_TYPE.GUIDE: {
+    // Two chunk names, one payload and one decoder. `SOURCES` is the contract
+    // the backend is moving to; `GUIDE` is the v2 envelope it ships in during
+    // the rollout (see `MESSAGE_TYPE.GUIDE`). The chunk arrives BEFORE or
+    // between the answer's text deltas, so the reducer — not this decoder —
+    // owns attaching it to the right turn.
+    case MESSAGE_TYPE.GUIDE:
+    case MESSAGE_TYPE.SOURCES: {
       const event = sourceMetadataEvent(data.payload);
       return event ? { ...event, ...seq } : null;
     }

package/src/chat-protocol/source-metadata.ts

@@ -1,8 +1,8 @@
 /**
  * Source-metadata payload → `{ sources, refs }`.
  *
- * ONE decoder for two arrival paths: the live `ATTACHMENTS` NATS chunk and the
- * persisted row of the same name in dialog history. That is the whole point
+ * ONE decoder for two arrival paths: the live `GUIDE`/`SOURCES` NATS chunk and
+ * the persisted row of the same name in dialog history. That is the whole point
  * of putting it here rather than in either consumer — a reloaded thread has to
  * render identically to the live turn, and two parsers is exactly how that stops
  * being true.
@@ -313,29 +313,6 @@ export function sourceMetadataEvent(payload: unknown): SourcesEvent | null {
   };
 }
 
-/** `null` fields dropped, at any depth. */
-function withoutNulls(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(withoutNulls);
-  if (!isRecord(value)) return value;
-  return Object.fromEntries(
-    Object.entries(value)
-      .filter(([, field]) => field !== null)
-      .map(([key, field]) => [key, withoutNulls(field)]),
-  );
-}
-
-/**
- * Decode one typed `ATTACHMENTS` record — the live chunk or the persisted
- * `AttachmentsData` row, which carry `sources` / `videos` / `cards` directly.
- *
- * GraphQL answers an unset field with `null` where the live chunk omits it, so
- * nulls are read as absent: a reloaded source must not gain a
- * `targetPlatform: null` ("no destination") the live one never carried.
- */
-export function attachmentsEvent(record: unknown): SourcesEvent | null {
-  return sourceMetadataEvent(withoutNulls(record));
-}
-
 /** What one assistant answer carries: its citations and its expandable refs. */
 export interface SourceMetadata {
   sources?: ChatSource[];

package/src/components/chat/types/message.types.ts

@@ -12,13 +12,15 @@ export const MESSAGE_TYPE = {
   TEXT: 'TEXT',
   THINKING: 'THINKING',
   ASK: 'ASK',
-  /** Per-answer attachments (cited documents, videos, entity cards).
+  /** Per-answer source metadata (documents, videos, entity cards).
    *
-   *  `ATTACHMENTS` carries `sources` / `videos` / `cards` on the record itself.
-   *  `GUIDE` is the envelope it replaced — the same arrays under `payload` —
-   *  and stays only until every backend ships `ATTACHMENTS`. */
-  ATTACHMENTS: 'ATTACHMENTS',
+   *  TWO names for ONE payload, on purpose. `SOURCES` is the contract the
+   *  backend is moving to; `GUIDE` is the envelope it ships in today, reused
+   *  from Guide Mode v2 so a released frontend keeps working during the v2→v3
+   *  rollout. Both decode through the same path, so dropping `GUIDE` later is a
+   *  deletion here and nothing else. */
   GUIDE: 'GUIDE',
+  SOURCES: 'SOURCES',
   EXECUTING_TOOL: 'EXECUTING_TOOL',
   EXECUTED_TOOL: 'EXECUTED_TOOL',
   APPROVAL_REQUEST: 'APPROVAL_REQUEST',
@@ -410,7 +412,7 @@ export interface ThinkingMessageData extends MessageDataBase {
  *
  * Lives here, beside `Message`, because BOTH transports produce it now: the SSE
  * adapter reads it off the per-turn metadata frame, and the NATS path decodes it
- * out of an `ATTACHMENTS` chunk. It used to be declared inside
+ * out of a `GUIDE`/`SOURCES` chunk. It used to be declared inside
  * `use-sse-chat-adapter`, which made "a Guide answer's citations" structurally a
  * property of one transport — `use-sse-chat-adapter` still re-exports the name
  * so existing imports keep working.
@@ -449,20 +451,13 @@ export interface ChatSource {
   label?: string;
 }
 
-/** Persisted attachments row (GraphQL `AttachmentsData`). The arrays are the
- *  SAME ones the live chunk carries, so history and realtime share one decoder
- *  (`attachmentsEvent`) and cannot drift apart. Left untyped: it is unvalidated
- *  wire data, and the decoder is what turns it into `ChatSource[]` / `ChatRef[]`. */
-export interface AttachmentsMessageData extends MessageDataBase {
-  type: 'ATTACHMENTS';
-  sources?: unknown;
-  videos?: unknown;
-  cards?: unknown;
-}
-
-/** The envelope `ATTACHMENTS` replaced: the same arrays under `payload`. */
+/** Persisted source-metadata row. `payload` is the SAME object the live chunk
+ *  carries, so history and realtime share one decoder (`sourceMetadataEvent`)
+ *  and cannot drift apart. Left as an open record here rather than typed
+ *  structurally: it is unvalidated wire data, and the decoder is what turns it
+ *  into `ChatSource[]` / `ChatRef[]`. */
 export interface SourceMetadataMessageData extends MessageDataBase {
-  type: 'GUIDE';
+  type: 'GUIDE' | 'SOURCES';
   payload?: unknown;
 }
 
@@ -608,7 +603,6 @@ export type MessageData =
   | TextMessageData
   | ThinkingMessageData
   | AskMessageData
-  | AttachmentsMessageData
   | SourceMetadataMessageData
   | ExecutingToolMessageData
   | ExecutedToolMessageData
@@ -660,7 +654,7 @@ export interface ProcessedMessage {
    *  Absent when the source row(s) carried no seq. */
   streamSeq?: number;
   /** Documents this answer cited — see `Message.sources`, the same field.
-   *  Replayed from the turn's persisted `ATTACHMENTS` row, so a reloaded
+   *  Replayed from the turn's persisted `GUIDE`/`SOURCES` row, so a reloaded
    *  answer carries the citations the live one did. */
   sources?: ChatSource[];
   /** Entity references this answer's metadata described — see `Message.refs`. */

package/src/components/chat/types/unified-chat-state.types.ts

@@ -239,7 +239,7 @@ export interface UnifiedChatMessage {
   /**
    * Documents this answer cited, rendered as chips beneath it. Produced by
    * BOTH transports now — SSE reads them off the per-turn metadata frame, NATS
-   * decodes them out of an `ATTACHMENTS` chunk.
+   * decodes them out of a `GUIDE`/`SOURCES` chunk.
    */
   sources?: ChatSource[];
   /**

package/src/components/chat/utils/process-historical-messages.ts

@@ -34,12 +34,7 @@ import {
 // One normalizer for ask rows, shared with the live decoder — history and the
 // stream must agree on which options are usable.
 import { normalizeAskOptions } from '../../../chat-protocol/nats-decoder';
-import {
-  attachmentsEvent,
-  mergeSourceMetadata,
-  sourceMetadataEvent,
-  type SourceMetadata,
-} from '../../../chat-protocol/source-metadata';
+import { mergeSourceMetadata, sourceMetadataEvent, type SourceMetadata } from '../../../chat-protocol/source-metadata';
 import { applyApprovalStatusToSegment } from '../stream/message-mutations';
 import {
   MESSAGE_TYPE,
@@ -127,14 +122,11 @@ export function decodeHistoricalMessageData(data: MessageData): ChatStreamEvent
       }
       return null;
 
-    // Persisted attachments, through the SAME decoder the live chunk uses
-    // (`attachmentsEvent`). That shared parse is the whole reason a reloaded
+    // Persisted source metadata, through the SAME decoder the live chunk uses
+    // (`sourceMetadataEvent`). That shared parse is the whole reason a reloaded
     // answer renders identically to the one the reader watched arrive.
-    case MESSAGE_TYPE.ATTACHMENTS:
-      return attachmentsEvent(data);
-
-    // The envelope `ATTACHMENTS` replaced (see `MESSAGE_TYPE.GUIDE`).
     case MESSAGE_TYPE.GUIDE:
+    case MESSAGE_TYPE.SOURCES:
       return 'payload' in data ? sourceMetadataEvent(data.payload) : null;
 
     // Same completeness gate as the live decoder (`decodeNatsChunk`): a