@flamingo-stack/openframe-frontend-core 0.0.508 → 0.0.509

package/src/chat-protocol/encode.ts

@@ -0,0 +1,71 @@
+/**
+ * SSE wire-protocol encoders — the emit side of the framing contract in
+ * `./frames.ts`. Server-safe (TextEncoder only). The hub's stream route
+ * consumes these so emitter and decoder can never drift.
+ */
+
+import {
+  FRAME_TERMINATOR,
+  END_OF_LEADING,
+  TRAILER_SENTINEL,
+  type SseLeadingFrame,
+  type SseTrailingUsageFrame,
+} from './frames'
+
+const encoder = new TextEncoder()
+
+/** Matches every framing sentinel byte: `\0`, `\x1E`, `\x1F`. THE one
+ *  regex — `stripSentinelBytes` is its only consumer. */
+const SENTINEL_BYTES_RE = /[\u0000\u001E\u001F]/g
+
+/**
+ * Remove the SSE framing sentinel bytes (`\0`, `\x1E`, `\x1F`) from model
+ * text. Exported as a STANDALONE helper — not just folded into
+ * `encodeTextDelta` — because producers must strip at the point where they
+ * first take custody of the text, BEFORE any local accumulation.
+ *
+ * Concretely: the hub's `claude-util.ts` accumulates `state.answerText` for
+ * persistence + telemetry. If stripping only happened at encode time, the
+ * persisted/telemetered answer would diverge, character for character, from
+ * the bytes the user actually received whenever the model echoes a control
+ * byte. Both sides call this, so there is exactly ONE definition of "which
+ * bytes are framing" in the whole system — do not re-declare the regex.
+ *
+ * Idempotent and per-character, so it distributes over concatenation:
+ * `strip(a + b) === strip(a) + strip(b)` — safe to apply per-delta or on the
+ * accumulated string interchangeably.
+ */
+export function stripSentinelBytes(text: string): string {
+  return text.replace(SENTINEL_BYTES_RE, '')
+}
+
+/** Encode one leading frame: JSON + `\0` terminator. */
+export function encodeLeadingFrame(frame: SseLeadingFrame): Uint8Array {
+  return encoder.encode(JSON.stringify(frame) + FRAME_TERMINATOR)
+}
+
+/** Encode the single `\x1E` end-of-leading-frames sentinel. */
+export function encodeEndOfLeading(): Uint8Array {
+  return encoder.encode(END_OF_LEADING)
+}
+
+/**
+ * Encode a raw answer-text delta. STRIPS the framing sentinel bytes via
+ * `stripSentinelBytes` so model-echoed control bytes can no longer
+ * mis-frame the stream (a literal `\x1F` in the answer used to flip the
+ * client into trailer mode and swallow the rest of the answer PLUS the real
+ * usage trailer — characterized by golden fixture (d)). Forward-looking
+ * encoder fix only; the decoder's behavior is unchanged.
+ *
+ * Producers that ALSO accumulate the text locally (persistence, telemetry)
+ * must call `stripSentinelBytes` on their own copy — see its docblock.
+ */
+export function encodeTextDelta(text: string): Uint8Array {
+  return encoder.encode(stripSentinelBytes(text))
+}
+
+/** Encode the trailing usage frame: `\x1F` + JSON, no terminator
+ *  (runs to stream end). */
+export function encodeTrailingUsageFrame(frame: SseTrailingUsageFrame): Uint8Array {
+  return encoder.encode(TRAILER_SENTINEL + JSON.stringify(frame))
+}

package/src/chat-protocol/env-flag.ts

@@ -0,0 +1,39 @@
+/**
+ * `envFlagEnabled` — THE cross-repo predicate for reading a boolean env flag.
+ *
+ * WHY IT LIVES HERE: the same flag is read on BOTH sides of the guide-chat
+ * seam and each side had grown its own reading of it. The hub parsed the
+ * value (`'0'` / `'false'` / `'off'` mean OFF); the producing app used bare
+ * `Boolean(process.env.X)`, under which every non-empty string — including
+ * `'0'` and `'false'` — is TRUE.
+ *
+ * That divergence failed OPEN on the one flag that gates a security boundary.
+ * `TRUSTED_INGRESS_SETS_REAL_IP` is an operator's assertion that a reverse
+ * proxy OVERWRITES the client-IP headers; without it those headers are
+ * attacker-writable and must not be read. An operator writing `=0` to mean
+ * "off" got the hub honoring that while the producer read `x-real-ip` /
+ * `x-forwarded-for` anyway and forwarded the value as `x-chat-ip`, which the
+ * hub then trusts verbatim under the service token. A rate-limit-bucket
+ * spoof, reachable through a plausible operator typo.
+ *
+ * Both repos already depend on this package and `./chat-protocol` is its
+ * server-safe subpath (no React, no browser APIs), so this is the one place
+ * both sides can share — same reasoning that moved `normalizeIpForBucketKey`
+ * here. Keep it as ONE definition: a second copy is what caused the drift.
+ *
+ * Contract:
+ *   - unset, empty, or whitespace-only  → `false`;
+ *   - `'0'`, `'false'`, `'off'`         → `false` (case- and
+ *     surrounding-whitespace-insensitive);
+ *   - any other non-empty value         → `true`.
+ *
+ * `process.env` is read PER CALL, never module-hoisted, so tests, preview and
+ * prod all observe the live value rather than whatever was present at
+ * module-eval time.
+ */
+export function envFlagEnabled(name: string): boolean {
+  const raw = process.env[name]
+  if (!raw) return false
+  const v = raw.trim().toLowerCase()
+  return v !== '' && v !== '0' && v !== 'false' && v !== 'off'
+}

package/src/chat-protocol/events.ts

@@ -0,0 +1,254 @@
+/**
+ * Normalized chat stream events — the transport-agnostic event union BOTH
+ * decoders (SSE byte framing in `./decode.ts`, NATS chunks in
+ * `./nats-decoder.ts`) emit. Phase 3 of the chat unification makes the
+ * reducer consume these directly; today the SSE adapter maps them back to
+ * legacy `MessageSegment` yields.
+ *
+ * Server-safe: no React, no browser APIs.
+ */
+
+// The wire-frame shapes these events carry through are defined ONCE in
+// `./frames.ts` — reuse them here rather than restating their fields.
+import type {
+  ApprovalRequestField,
+  DecisionResolvedFrame,
+  UsageTelemetry,
+} from './frames'
+
+/** Optional envelope on every event. `seq` carries the transport's
+ *  stream sequence (JetStream `streamSeq` on NATS; unused on SSE). */
+interface ChatStreamEventBase {
+  seq?: number
+}
+
+/** Stream entered answer-text mode (SSE: the `\x1E` sentinel or the
+ *  JSON-parse-failure fallback; NATS: MESSAGE_START).
+ *  `implicit` is true ONLY for the SSE fallback path where a
+ *  non-JSON leading buffer flips straight into text mode — consumers
+ *  that flush coalesced thinking on turn-start must SKIP the flush for
+ *  implicit starts (legacy adapter parity: the fallback path never
+ *  flushed pending thinking before the text). */
+export interface TurnStartEvent extends ChatStreamEventBase {
+  type: 'turn-start'
+  implicit?: boolean
+}
+
+export interface TurnEndEvent extends ChatStreamEventBase {
+  type: 'turn-end'
+}
+
+/** Answer text delta. `leading: true` marks SSE `text-leading` frames
+ *  (model preamble prose emitted BEFORE the tool approval card). */
+export interface TextDeltaEvent extends ChatStreamEventBase {
+  type: 'text-delta'
+  text: string
+  leading?: boolean
+}
+
+/** Thinking delta — APPEND-ONLY contract: each event carries the next
+ *  verbatim slice; consumers accumulate. Decoders never diff. */
+export interface ThinkingDeltaEvent extends ChatStreamEventBase {
+  type: 'thinking-delta'
+  text: string
+}
+
+/** Guide-body delta (NATS `GUIDE` chunk) — the assistant's how-to /
+ *  documentation answer, rendered as a titled "OpenFrame Guide" card rather
+ *  than bare prose. Same APPEND-ONLY contract as `text-delta` /
+ *  `thinking-delta`: each event carries the next verbatim slice and consumers
+ *  coalesce into the trailing `guide` segment. NATS-only today — the SSE
+ *  frame grammar has no guide frame — but it lives in the shared union
+ *  because the reducer is transport-agnostic. */
+export interface GuideDeltaEvent extends ChatStreamEventBase {
+  type: 'guide-delta'
+  text: string
+}
+
+export interface StatusEvent extends ChatStreamEventBase {
+  type: 'status'
+  phase: 'thinking'
+}
+
+/** NATS tool execution progress (EXECUTING_TOOL / EXECUTED_TOOL). */
+export interface ToolExecutionEvent extends ChatStreamEventBase {
+  type: 'tool-execution'
+  data: {
+    type: 'EXECUTING_TOOL' | 'EXECUTED_TOOL'
+    integratedToolType: string
+    toolFunction: string
+    toolTitle?: string
+    /**
+     * Human-readable "why this tool is running" line, rendered as the body of
+     * the tool card. Carried by the EXECUTING chunk ONLY — the EXECUTED one
+     * never repeats it, and the accumulator's merge keeps whatever the
+     * EXECUTING segment held (`toolData.toolExplanation ?? existing`). Omitting
+     * it from this contract blanks the card for the whole run, live and on
+     * replay, which is exactly what happened while it was missing here.
+     */
+    toolExplanation?: string
+    parameters?: Record<string, unknown>
+    result?: string
+    success?: boolean
+    toolExecutionRequestId?: string
+  }
+}
+
+/** Single tool call inside a batch approval request (NATS). */
+export interface ApprovalToolCall {
+  toolExecutionRequestId: string
+  toolName: string
+  toolTitle?: string
+  toolExplanation?: string
+  toolType?: string
+  requiresApproval: boolean
+  approvalType?: string | null
+  toolCallArguments?: Record<string, unknown> | null
+}
+
+/** A tool call awaits user approval. SSE fills `command`/`fields`
+ *  (card-ready payload); NATS fills `command`/`explanation` or
+ *  `toolCalls` (batch form). */
+export interface ApprovalRequestEvent extends ChatStreamEventBase {
+  type: 'approval-request'
+  requestId: string
+  /** SSE: the write tool's name. NATS: approval tier (USER/ADMIN/…). */
+  approvalType?: string
+  command?: string
+  explanation?: string
+  fields?: ApprovalRequestField[]
+  toolCalls?: ApprovalToolCall[]
+  status?: 'pending'
+}
+
+/** An approval request was resolved (SSE `decision_resolved` frame /
+ *  NATS APPROVAL_RESULT chunk). */
+export interface ApprovalResolvedEvent extends ChatStreamEventBase {
+  type: 'approval-resolved'
+  requestId?: string
+  status: 'approved' | 'rejected'
+  ok?: boolean
+  toolName?: string
+  approvalType?: string
+  resolvedByName?: string | null
+  receiptText?: string
+  /** Inline post-approve card: the ref payload + its documentType +
+   *  the `[card://…]` marker (SSE only). */
+  cardRef?: unknown
+  cardType?: string
+  marker?: string
+  result?: DecisionResolvedFrame['result']
+  willAutoContinue?: boolean
+}
+
+/** Per-turn metadata. Raw wire values pass through UNVALIDATED — the
+ *  consumer replicates the legacy truthiness/typeof gates (so a
+ *  malformed frame degrades identically to the pre-SSOT parser). */
+export interface ChatMetadataEvent extends ChatStreamEventBase {
+  type: 'metadata'
+  provider?: string | null
+  modelLabel?: string | null
+  /** Raw model id (SSE `meta.model`; NATS `modelName`). */
+  modelName?: string | null
+  contextWindowMaxTokens?: number | null
+  sources?: unknown
+  refs?: unknown
+  scrollAnchor?: unknown
+  /** Server-minted conversation id (`ChatMetadataFrame.conversationId`),
+   *  passed through raw like every other catch-all field — the consumer
+   *  applies the `typeof === 'string' && truthy` gate. */
+  conversationId?: string | null
+  routing?: {
+    routedComplexity: string
+    routedModel?: string
+    routedThinkingBudget: number | null
+  }
+}
+
+/** SSE usage frames — raw wire keys (snake_case) preserved. */
+export interface UsageEvent extends ChatStreamEventBase {
+  type: 'usage'
+  stage: 'start' | 'end'
+  input_tokens?: number
+  output_tokens?: number
+  cache_read_input_tokens?: number
+  cache_creation_input_tokens?: number
+  hit_rate_pct?: number
+  telemetry?: UsageTelemetry
+  /** Left OPAQUE on purpose: the consumer (`chat-stream-reducer`'s
+   *  `applySseUsage`) re-validates every nested field with the legacy
+   *  truthiness/typeof gates, so a malformed frame degrades identically
+   *  to the pre-SSOT parser. Typing it would imply guarantees the wire
+   *  does not make. */
+  breakdown?: unknown
+  debug?: unknown
+}
+
+/** NATS TOKEN_USAGE chunk (camelCase backend shape). */
+export interface TokenUsageEvent extends ChatStreamEventBase {
+  type: 'token-usage'
+  inputTokensSize: number
+  outputTokensSize: number
+  totalTokensSize: number
+  contextSize: number
+}
+
+export interface CompactionEvent extends ChatStreamEventBase {
+  type: 'compaction'
+  phase: 'start' | 'end'
+  summary?: string
+}
+
+export interface ErrorEvent extends ChatStreamEventBase {
+  type: 'error'
+  title: string
+  details?: string
+}
+
+/** Non-assistant message on the stream (NATS): the user's own message
+ *  echo (`message-request`), an operator direct message, or a system
+ *  line. */
+/**
+ * Dialog participant owner type. The two members below are the ones clients
+ * BRANCH ON (admin-vs-not decides echo dedup and author styling); the union
+ * stays open (`string & {}`) because the wire may carry other roles that the
+ * client treats as "not admin". Always compare against `CHAT_OWNER_ADMIN`,
+ * never a bare `'ADMIN'` literal — a typo in a literal silently disables
+ * dedup instead of failing to compile.
+ */
+export type ChatOwnerType = 'ADMIN' | 'CLIENT' | (string & {})
+
+/** Canonical ADMIN owner-type token (see `ChatOwnerType`). */
+export const CHAT_OWNER_ADMIN = 'ADMIN'
+
+export interface ParticipantEvent extends ChatStreamEventBase {
+  type: 'participant'
+  kind: 'message-request' | 'direct-message' | 'system'
+  text: string
+  ownerType?: ChatOwnerType
+  displayName?: string
+  userId?: string
+  contextItems?: Array<{ type: string; id: string; label: string }>
+}
+
+export interface DialogClosedEvent extends ChatStreamEventBase {
+  type: 'dialog-closed'
+}
+
+export type ChatStreamEvent =
+  | TurnStartEvent
+  | TurnEndEvent
+  | TextDeltaEvent
+  | ThinkingDeltaEvent
+  | GuideDeltaEvent
+  | StatusEvent
+  | ToolExecutionEvent
+  | ApprovalRequestEvent
+  | ApprovalResolvedEvent
+  | ChatMetadataEvent
+  | UsageEvent
+  | TokenUsageEvent
+  | CompactionEvent
+  | ErrorEvent
+  | ParticipantEvent
+  | DialogClosedEvent

package/src/chat-protocol/frames.ts

@@ -0,0 +1,245 @@
+/**
+ * SSE wire-protocol frame shapes — the byte-level contract between the
+ * hub's chat stream emitter (`multi-platform-hub/lib/utils/claude-util.ts`)
+ * and the lib's SSE decoder (`./decode.ts`).
+ *
+ * Wire format (custom byte framing, NOT standard SSE `data:` lines):
+ *
+ *   [JSON frame]\0 [JSON frame]\0 …  \x1E  <raw UTF-8 answer deltas>  \x1F [JSON usage trailer]
+ *
+ *   1. LEADING frames — each a JSON object terminated by `\0`
+ *      (FRAME_TERMINATOR). Status, metadata, routing, live thinking
+ *      deltas, usage:start, tool approval frames.
+ *   2. ONE `\x1E` byte (END_OF_LEADING) — flips the stream into raw
+ *      UTF-8 answer-text mode.
+ *   3. `\x1F` (TRAILER_SENTINEL) + one JSON usage frame running to
+ *      stream end (no terminator).
+ *
+ * Server-safe: no React, no browser APIs beyond TextEncoder/TextDecoder.
+ */
+
+// =============================================================================
+// Sentinel constants
+// =============================================================================
+
+/** Terminates every leading JSON frame. */
+export const FRAME_TERMINATOR = '\0'
+/** Record Separator — end of leading frames, start of raw answer text. */
+export const END_OF_LEADING = '\x1E'
+/** Unit Separator — start of the trailing usage JSON frame. */
+export const TRAILER_SENTINEL = '\x1F'
+
+// =============================================================================
+// Routing types (moved verbatim from the hub's `lib/chat/wire-frames.ts`;
+// `RouteComplexity` is lib-local so the lib never imports hub code)
+// =============================================================================
+
+/** Server-side routing complexity tiers. Mirror of the hub's
+ *  `lib/constants/ai-models.ts` union — kept as a lib-local literal type
+ *  so the wire SSOT has zero hub imports. The DECODER accepts any string
+ *  (older/newer servers may ship values outside this union). */
+export type RouteComplexity = 'trivial' | 'default' | 'complex' | 'deep'
+
+/**
+ * Routing decision frame. Emitted once per turn as a LEADING frame
+ * (between metadata and the `\x1E` end-of-leading-frames sentinel) when
+ * the server's `decideRoute()` produces a `Route`.
+ *
+ * Field names use the `routed*` prefix on PURPOSE — the client's
+ * catch-all leading-frame branch inspects `meta.model` / `meta.modelLabel`.
+ * A bare `model` field on this frame would OVERWRITE the metadata frame's
+ * modelLabel and break the <ModelDisplay> badge. The `routed` prefix
+ * sidesteps that collision.
+ *
+ * Older clients that don't recognize `kind: 'routing'` silently drop
+ * the frame (the catch-all only matches frames carrying known fields
+ * like `sources` / `refs` / `modelLabel`).
+ */
+export interface RoutingFrame {
+  kind: 'routing'
+  routedComplexity: RouteComplexity
+  routedModel: string
+  routedThinkingBudget: number
+}
+
+/**
+ * Optional field on the trailing usage frame's `breakdown`. Surfaces
+ * per-route attribution to the admin test console so an operator can
+ * see "this turn ran on Haiku/trivial/$0.0005" without re-parsing the
+ * stream. Additive: clients that ignore unknown keys keep working.
+ */
+export interface RoutedAnswerBreakdown {
+  model: string
+  complexity: RouteComplexity
+  thinkingBudget: number
+}
+
+// =============================================================================
+// Leading frames
+// =============================================================================
+
+/** First frame on every stream — lets the shell render "Thinking…"
+ *  within ~200ms, before any upstream byte arrives. */
+export interface StatusThinkingFrame {
+  status: 'thinking'
+}
+
+/** Per-turn metadata frame. The emitter sends `options.metadata`
+ *  verbatim; a separate refs-only frame may follow with the same shape.
+ *  All fields optional — the decoder's catch-all treats ANY frame that
+ *  didn't match a `kind` discriminant as metadata-ish. */
+export interface ChatMetadataFrame {
+  /** Retrieval sources for the source-chip strip. Host-defined row
+   *  shape (`ChatSource` on the adapter side) — opaque at wire level. */
+  sources?: unknown[]
+  /** Per-row refs for inline object cards, keyed `<type>:<id>`. */
+  refs?: Record<string, unknown>
+  /** Raw model id (e.g. 'claude-sonnet-x'). Presence alone triggers the
+   *  client's meta merge; the value itself is not stored. */
+  model?: string
+  modelLabel?: string
+  provider?: string
+  contextWindowMaxTokens?: number
+  /** Per-message viewport-positioning hint ('top' | 'bottom'). */
+  scrollAnchor?: string
+  /** SERVER-minted conversation trace id (`chat_conversations.id`),
+   *  echoed on every turn's leading metadata frame. The client never
+   *  generates ids — the first turn of a session goes out id-less, the
+   *  server mints one and echoes it here, and the adapter persists the
+   *  echoed id as its ONLY local state (see
+   *  `chat-conversation-storage.ts` on the consumer side). */
+  conversationId?: string
+}
+
+/** Live adaptive-thinking delta. WIRE IS ALREADY DELTA (Anthropic
+ *  thinking_delta slices) — decoders must NOT diff or re-accumulate. */
+export interface ThinkingDeltaFrame {
+  kind: 'thinking-delta'
+  text: string
+}
+
+/** Usage frame emitted as a LEADING frame right after Anthropic's
+ *  message_start (stage='start'). */
+export interface UsageStartFrame {
+  kind: 'usage'
+  stage: 'start'
+  input_tokens: number
+  cache_read_input_tokens?: number
+  cache_creation_input_tokens?: number
+}
+
+/** Model preamble prose written BEFORE a tool_use block — emitted as a
+ *  standalone leading frame so it isn't stranded behind the approval
+ *  card (the `\x1E` sentinel is suppressed on tool turns). */
+export interface TextLeadingFrame {
+  kind: 'text-leading'
+  text: string
+}
+
+/** Tool invocation failed server-side (proposal persist error,
+ *  validation, ownership denial …). */
+export interface ToolErrorFrame {
+  kind: 'tool_error'
+  toolName?: string
+  toolUseId?: string
+  message: string
+}
+
+export interface ApprovalRequestField {
+  label: string
+  value: string
+}
+
+/** The model called a write tool; the server persisted a proposal and
+ *  ships a card-ready payload. Shape mirrors the hub's `onToolUse`
+ *  return in `lib/data/doc-chat-utils.ts`. */
+export interface ApprovalRequestFrame {
+  kind: 'approval_request'
+  proposalId: string
+  toolName: string
+  title?: string
+  fields?: ApprovalRequestField[]
+  preamble?: string | null
+  args?: Record<string, unknown>
+  expiresAt?: string
+  ttlSeconds?: number
+}
+
+/** Server-driven post-approve / post-reject frame (confirm-tool route).
+ *  Mirror of the hub's `DecisionResolvedFrame` in
+ *  `lib/data/chat-agent-utils.ts` (tool_name widened to string — the
+ *  known-write-tool whitelist is host-side knowledge). */
+export interface DecisionResolvedFrame {
+  kind: 'decision_resolved'
+  /** The proposal this decision resolved — locates the SOURCE approval
+   *  card so the shell can flip its status + append the receipt. */
+  proposalId: string
+  ok: boolean
+  action: 'approved' | 'rejected'
+  tool_name?: string
+  result?: {
+    ticket_id?: string
+    status?: string | null
+    mirror_synced?: boolean
+  }
+  card?: {
+    type: string
+    marker: string
+    ref: unknown
+  }
+  /** True when the server WILL pipe an auto-continuation turn after
+   *  this frame. */
+  willAutoContinue: boolean
+  /** Pre-rendered receipt copy from the source strategy's
+   *  `receiptRenderer` — client renders verbatim. */
+  receiptText?: string
+}
+
+/** Every leading frame the emitter can produce. */
+export type SseLeadingFrame =
+  | StatusThinkingFrame
+  | ChatMetadataFrame
+  | RoutingFrame
+  | ThinkingDeltaFrame
+  | UsageStartFrame
+  | TextLeadingFrame
+  | ToolErrorFrame
+  | ApprovalRequestFrame
+  | DecisionResolvedFrame
+
+// =============================================================================
+// Trailing usage frame
+// =============================================================================
+
+/** Card/chip emission counts for admin adoption tooling. */
+export interface UsageTelemetry {
+  cards: number
+  chips: number
+  sentences: number
+  answerLen: number
+}
+
+/** Trailing usage frame — `\x1F` + JSON, runs to stream end (no
+ *  terminator). `stage: 'display'` is a legacy alias the decoder treats
+ *  identically to `'end'`. */
+export interface SseTrailingUsageFrame {
+  kind: 'usage'
+  stage: 'end' | 'display'
+  input_tokens?: number
+  output_tokens?: number
+  cache_read_input_tokens?: number
+  cache_creation_input_tokens?: number
+  hit_rate_pct?: number
+  telemetry?: UsageTelemetry
+  /** Cross-call usage breakdown (Haiku rewriter / classifier /
+   *  summarizer + routed-answer attribution). */
+  breakdown?: {
+    haikuRewriter?: { input: number; output: number }
+    haikuClassifier?: { input: number; output: number }
+    haikuSummarizer?: { input: number; output: number }
+    routedAnswer?: RoutedAnswerBreakdown
+  }
+  /** Gated deep-debug payload (only present when the request carried
+   *  the privileged debug secret). */
+  debug?: Record<string, unknown>
+}

package/src/chat-protocol/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Chat wire-protocol SSOT.
+ *
+ * The byte-level SSE framing contract (frames + encode + decode) and the
+ * transport-agnostic `ChatStreamEvent` union both the SSE and NATS
+ * decoders emit. Published as the server-safe `./chat-protocol` subpath —
+ * no React, no browser APIs beyond TextEncoder/TextDecoder — so the hub's
+ * stream route (emit side) and the lib's chat hooks (decode side) share
+ * one protocol module.
+ */
+
+export * from './frames'
+export * from './events'
+export * from './encode'
+export * from './decode'
+export * from './nats-decoder'
+// Cross-repo IP bucket-key normalizer (producer app + consumer hub share it).
+export * from './ip-normalize'
+// Cross-repo env-flag predicate — the trust assertion that gates the IP
+// forwarding above must be parsed IDENTICALLY on both sides of the seam.
+export * from './env-flag'