serverless-ircd 0.5.0 → 0.7.0

package/packages/irc-core/src/protocol/standard-replies.ts

@@ -0,0 +1,277 @@
+/**
+ * IRCv3 `standard-replies` — `FAIL` / `WARN` / `NOTE` dispatch helper.
+ *
+ * Spec: https://ircv3.net/specs/extensions/standard-replies-3.0
+ *
+ * Modern IRC clients that negotiated the `standard-replies` cap accept the
+ * structured reply form
+ *
+ *     :<server> FAIL   <command> <code> [<context>...] :<description>
+ *     :<server> WARN   <command> <code> [<context>...] :<description>
+ *     :<server> NOTE   <command> <code> [<context>...] :<description>
+ *
+ * in place of the legacy `:server NNN nick ... :trailing` numerics for a
+ * curated subset of errors. Numeric-only replies (MOTD lines, NAMES,
+ * welcome block, …) stay on the numeric form — only the curated error
+ * numerics are translated.
+ *
+ * This module is the data-driven mapping plus a single pure dispatch
+ * helper ({@link toStandardReply}) that the dispatch / outbound layer
+ * applies per recipient. Translating at the outbound layer (rather than
+ * scattering `if (caps.has('standard-replies'))` through every reducer)
+ * keeps the reducer code cap-agnostic, matching the model already used
+ * for `server-time` and `message-tags`.
+ *
+ * Reducers keep emitting the canonical numeric line; the dispatch layer
+ * runs this helper to translate the curated numerics for cap-enabled
+ * recipients and passes everything else through verbatim.
+ */
+
+import type { RawLine } from '../effects.js';
+import { Numerics } from './numerics.js';
+
+/** One of the IRCv3 standard-reply verbs. */
+export type ReplyKind = 'FAIL' | 'WARN' | 'NOTE';
+
+/**
+ * One row of the {@link numericToStandardReply} table, as a discriminated
+ * union over where the COMMAND token comes from on the wire.
+ *
+ *  - When {@link CommandFromMiddle.commandFromMiddle} is `true`, the
+ *    numeric's middle parameter IS the failed command name (true for
+ *    `461 ERR_NEEDMOREPARAMS`, whose middle is the command the client
+ *    undersupplied).
+ *  - When {@link CommandFixed.commandFromMiddle} is `false`, a fixed
+ *    {@link CommandFixed.command} is emitted (true for `432`/`433`,
+ *    always `NICK`, and for SASL failures, always `AUTHENTICATE`).
+ *
+ * The discriminated union lets `pickCommand` return `mapping.command`
+ * directly in the fixed branch with no defensive `?? null` — the type
+ * system proves `command` is always set there.
+ */
+export type StandardReplyMapping = CommandFromMiddle | CommandFixed;
+
+/** A row whose COMMAND token comes from the numeric's middle parameter. */
+export interface CommandFromMiddle {
+  /** Discriminant: true → read COMMAND from `parsed.middle[0]`. */
+  commandFromMiddle: true;
+  /** Which of `FAIL`/`WARN`/`NOTE` to emit. */
+  kind: ReplyKind;
+  /** Stable wire code (`INVALID_PARAMS`, …). */
+  code: string;
+  /** Always false here — the middle is consumed as the command, not context. */
+  contextFromMiddle: false;
+}
+
+/** A row whose COMMAND token is a fixed string. */
+export interface CommandFixed {
+  /** Discriminant: false → read COMMAND from {@link command}. */
+  commandFromMiddle: false;
+  /** Which of `FAIL`/`WARN`/`NOTE` to emit. */
+  kind: ReplyKind;
+  /** Stable wire code (`NO_SUCH_CHANNEL`, `INVALID_NICK`, …). */
+  code: string;
+  /** Fixed command token emitted after the FAIL/WARN/NOTE verb. */
+  command: string;
+  /**
+   * True iff the numeric's middle parameter carries a context token
+   * (the bad nick, the bad channel) that should follow the code.
+   */
+  contextFromMiddle: boolean;
+}
+
+/**
+ * The curated numeric → standard-reply mapping.
+ *
+ * Only a deliberately small subset of error numerics is translated —
+ * the ones that carry enough context for the structured form to be a
+ * strict improvement over the bare numeric. Numeric-only families
+ * (MOTD, NAMES, the welcome block, mode replies, …) stay on the
+ * numeric form per the spec.
+ */
+export const numericToStandardReply: ReadonlyMap<number, StandardReplyMapping> = new Map<
+  number,
+  StandardReplyMapping
+>([
+  [
+    Numerics.ERR_NEEDMOREPARAMS,
+    {
+      kind: 'FAIL',
+      code: 'INVALID_PARAMS',
+      commandFromMiddle: true,
+      contextFromMiddle: false,
+    },
+  ],
+  [
+    Numerics.ERR_NOSUCHCHANNEL,
+    {
+      kind: 'FAIL',
+      code: 'NO_SUCH_CHANNEL',
+      commandFromMiddle: false,
+      command: 'JOIN',
+      contextFromMiddle: true,
+    },
+  ],
+  [
+    Numerics.ERR_ERRONEUSNICKNAME,
+    {
+      kind: 'FAIL',
+      code: 'INVALID_NICK',
+      commandFromMiddle: false,
+      command: 'NICK',
+      contextFromMiddle: true,
+    },
+  ],
+  [
+    Numerics.ERR_NICKNAMEINUSE,
+    {
+      kind: 'FAIL',
+      code: 'NICKNAME_IN_USE',
+      commandFromMiddle: false,
+      command: 'NICK',
+      contextFromMiddle: true,
+    },
+  ],
+  [
+    Numerics.ERR_SASLFAIL,
+    {
+      kind: 'FAIL',
+      code: 'SASL_FAILED',
+      commandFromMiddle: false,
+      command: 'AUTHENTICATE',
+      contextFromMiddle: false,
+    },
+  ],
+]);
+
+/**
+ * Translates a single outbound {@link RawLine} for a recipient whose
+ * negotiated caps are `caps`.
+ *
+ *  - If the recipient lacks the `standard-replies` cap, the line is
+ *    returned unchanged (the legacy numeric still ships).
+ *  - If the line is not a `:server NNN …` numeric, it is returned
+ *    unchanged (PRIVMSG, BATCH, FAIL/WARN/NOTE already emitted by
+ *    reducers, etc.).
+ *  - If the numeric is not in {@link numericToStandardReply}, the line
+ *    is returned unchanged.
+ *  - Otherwise the line is rewritten into the structured
+ *    `FAIL`/`WARN`/`NOTE` form using the table.
+ *
+ * The input is never mutated; the original object is returned whenever
+ * no translation occurred so callers can cheaply detect "no change".
+ */
+export function toStandardReply(line: RawLine, caps: ReadonlySet<string>): RawLine {
+  if (!caps.has('standard-replies')) return line;
+  if (!line.text.startsWith(':')) return line;
+
+  const parsed = parseNumericLine(line.text);
+  if (parsed === null) return line;
+
+  const mapping = numericToStandardReply.get(parsed.code);
+  if (mapping === undefined) return line;
+
+  const command = pickCommand(parsed, mapping);
+  if (command === null) return line;
+
+  // The structured form requires a `:description` token. A curated numeric
+  // missing its trailing parameter (malformed input that never ships from a
+  // reducer) is left on the bare numeric so we never emit an empty FAIL.
+  if (parsed.trailing === undefined) return line;
+
+  const context = pickContext(parsed, mapping);
+  const trailing = parsed.trailing;
+
+  const head = `:${parsed.server} ${mapping.kind} ${command} ${mapping.code}`;
+  const withContext = context !== null ? `${head} ${context}` : head;
+  return { text: `${withContext} :${trailing}` };
+}
+
+/** Internal: the parsed shape of a `:server NNN nick [middle] [:trailing]` line. */
+interface ParsedNumeric {
+  server: string;
+  code: number;
+  /** Every token between the nick and the trailing `:`-parameter. May be empty. */
+  middle: string[];
+  /** The trailing `:`-prefixed parameter, with the leading `:` stripped. */
+  trailing: string | undefined;
+}
+
+/**
+ * Parses a single `:server NNN ...` line into its components.
+ *
+ * Returns `null` for any shape this server does not emit for numerics:
+ * lines without a server prefix, lines whose second token is not a
+ * three-digit numeric, and lines with no nick token. The trailing
+ * `:`-parameter is optional (a handful of numerics — currently none in
+ * the curated set — ship without one).
+ */
+function parseNumericLine(text: string): ParsedNumeric | null {
+  // Strip the leading `:server ` prefix.
+  const firstSpace = text.indexOf(' ');
+  if (firstSpace === -1) return null;
+  const server = text.slice(1, firstSpace);
+
+  const rest = text.slice(firstSpace + 1);
+  const secondSpace = rest.indexOf(' ');
+  if (secondSpace === -1) return null;
+  const codeTok = rest.slice(0, secondSpace);
+  if (!/^\d{3}$/.test(codeTok)) return null;
+  const code = Number.parseInt(codeTok, 10);
+
+  const afterCode = rest.slice(secondSpace + 1);
+
+  // The nick token is mandatory between the code and the optional trailing.
+  // Empty after-code or an `:`-prefixed after-code (the trailing param
+  // immediately following the code) is malformed for a numeric this server
+  // emits; bail so the caller passes the line through verbatim.
+  if (afterCode.length === 0) return null;
+  if (afterCode[0] === ':') return null;
+
+  // Split off the trailing `:`-parameter if present.
+  const trailingIdx = findTrailingColon(afterCode);
+  let head = afterCode;
+  let trailing: string | undefined;
+  if (trailingIdx !== -1) {
+    head = afterCode.slice(0, trailingIdx).trimEnd();
+    trailing = afterCode.slice(trailingIdx + 1);
+  }
+
+  // head starts with the nick and optional middle params.
+  const tokens = head.length === 0 ? [] : head.split(' ');
+  if (tokens.length === 0) return null;
+  // Drop the nick — it is not used in the structured form (the reply is
+  // routed to a specific recipient, not addressed by nick).
+  const middle = tokens.slice(1);
+
+  return { server, code, middle, trailing };
+}
+
+/**
+ * Returns the index of the ` :` that introduces the trailing parameter,
+ * or `-1` when the line has no trailing. The leading space is required
+ * so a `:` inside a middle token (e.g. a malformed channel name) is not
+ * misread.
+ */
+function findTrailingColon(s: string): number {
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === ' ' && s[i + 1] === ':') return i + 1;
+  }
+  return -1;
+}
+
+/** Resolves the COMMAND token for the structured reply per the mapping. */
+function pickCommand(parsed: ParsedNumeric, mapping: StandardReplyMapping): string | null {
+  if (mapping.commandFromMiddle) {
+    const cmd = parsed.middle[0];
+    return cmd === undefined ? null : cmd;
+  }
+  return mapping.command;
+}
+
+/** Resolves the optional CONTEXT token for the structured reply per the mapping. */
+function pickContext(parsed: ParsedNumeric, mapping: StandardReplyMapping): string | null {
+  if (!mapping.contextFromMiddle) return null;
+  const ctx = parsed.middle[0];
+  return ctx ?? null;
+}

package/packages/irc-core/src/state/connection.ts

@@ -20,13 +20,21 @@ export type RegistrationState = 'pre-registration' | 'registering' | 'registered
 
 /**
  * User modes applied to a connection. The IRC user-mode letters are
- * `i` (invisible), `o` (oper), `w` (wallops), `s` (server notices).
+ * `i` (invisible), `o` (oper), `w` (wallops), `s` (server notices),
+ * `S` (TLS connected — read-only, set by the transport at registration).
  */
 export interface UserModes {
   invisible: boolean;
   oper: boolean;
   wallops: boolean;
   serverNotices: boolean;
+  /**
+   * User mode `S` — the connection arrived over TLS (wss or irc+tls).
+   * Read-only: set once by the registration reducer from
+   * {@link ConnectionState.secure} and never mutated afterwards. Not
+   * settable via `MODE` (the parser rejects `+S`/`-S` with `501`).
+   */
+  tls: boolean;
 }
 
 /**
@@ -84,6 +92,15 @@ export interface ConnectionState {
    * `CAP END` arrives (per IRCv3 capability-negotiation spec).
    */
   capNegotiating: boolean;
+  /**
+   * Transport-level fact: true when the connection arrived over TLS
+   * (`wss://` WebSocket or `irc+tls://` raw TCP). Set once by the adapter
+   * at construction from the platform's transport metadata and read by the
+   * registration reducer to surface user mode `S` ({@link UserModes.tls}).
+   * Defaults to `false` so existing callers (plain ws test harnesses) keep
+   * the pre-TLS-mode behaviour.
+   */
+  secure: boolean;
   /** IRCv3 capabilities negotiated via `CAP`. */
   caps: Set<string>;
   /** Away reason; absent when not away. */
@@ -109,6 +126,18 @@ export interface ConnectionState {
    * PART/re-JOIN cycle with no new activity replays nothing.
    */
   lastReadMarkers?: Map<string, string>;
+  /**
+   * Per-connection MONITOR watchlist (IRCv3 `MONITOR`). Each entry is the
+   * case-folded (rfc1459) spelling of a watched nick; the display spelling
+   * is resolved at emission time via the nick registry. Lazily allocated
+   * on first `MONITOR +`; persisted verbatim so a reconnect can restore
+   * the watchlist without re-issuing every `MONITOR` line.
+   *
+   * Capped at the deployment's `MONITOR=<n>` ISUPPORT value (default 30);
+   * the {@link monitorReducer} enforces the cap and emits `734
+   * ERR_MONLISTFULL` for rejected nicks.
+   */
+  monitorList?: Set<string>;
 }
 
 /**
@@ -147,6 +176,7 @@ export function createConnection(opts: CreateConnectionOptions): ConnectionState
     id: opts.id,
     registration: 'pre-registration',
     capNegotiating: false,
+    secure: false,
     caps: new Set<string>(),
     joinedChannels: new Set<ChanName>(),
     userModes: {
@@ -154,6 +184,7 @@ export function createConnection(opts: CreateConnectionOptions): ConnectionState
       oper: false,
       wallops: false,
       serverNotices: false,
+      tls: false,
     },
     lastSeen: opts.lastSeen ?? opts.connectedSince,
     connectedSince: opts.connectedSince,

package/packages/irc-core/src/types.ts

@@ -10,12 +10,14 @@ import type { Effect } from './effects.js';
 import type { FloodControlConfig } from './flood-control.js';
 import type {
   AccountStore,
+  AwayStore,
   Clock,
   IdFactory,
   MessageStore,
   MotdProvider,
   MtlsIdentityProvider,
   NickHistoryStore,
+  ReadMarkerStore,
 } from './ports.js';
 import type { IrcMessage } from './protocol/messages.js';
 import type { ConnectionState } from './state/connection.js';
@@ -33,6 +35,23 @@ export interface CloakingConfig {
   readonly cloakedSuffix?: string | undefined;
 }
 
+/**
+ * IRCv3 `sts` (Strict Transport Security) policy as seen by reducers.
+ * Mirrors the {@link StsConfigSchema} shape; the cap builder reads it to
+ * construct the `sts=…` advertisement per connection.
+ *
+ * Optional fields are widened to `T | undefined` to mirror Zod's
+ * `.optional()` output under `exactOptionalPropertyTypes: true`.
+ */
+export interface StsConfig {
+  /** Pin duration in seconds. */
+  readonly duration: number;
+  /** TLS listener port (plaintext advertisements only). */
+  readonly port: number;
+  /** Optional preload directive (plaintext advertisements only). */
+  readonly preload?: boolean | undefined;
+}
+
 /**
  * A single IRC operator credential. The {@link operReducer} consults the
  * configured list to authenticate `OPER <name> <password>`. Both fields are
@@ -127,6 +146,55 @@ export interface ServerConfig {
    * `exactOptionalPropertyTypes: true`.
    */
   chatHistoryPlaybackLimit?: number | undefined;
+  /**
+   * IRCv3 `sts` (Strict Transport Security) policy. `undefined` disables
+   * STS advertisement; an object supplies the policy the cap builder
+   * serializes per connection (plaintext vs TLS).
+   *
+   * Typed `StsConfig | undefined` to mirror Zod's optional output shape
+   * under `exactOptionalPropertyTypes: true`.
+   */
+  readonly sts?: StsConfig | undefined;
+  /**
+   * IRCv3 `draft/multiline` byte budget. Advertised as
+   * `draft/multiline=<n>` in `CAP LS` and enforced on every finalized
+   * multi-line batch. Defaults to {@link DEFAULT_MULTILINE_MAX_BYTES}
+   * (4096) when omitted; the parsed config always supplies a value.
+   *
+   * Typed `number | undefined` to mirror Zod's optional output shape
+   * under `exactOptionalPropertyTypes: true` so inline `ServerConfig`
+   * literals in tests may omit it.
+   */
+  readonly multilineMaxBytes?: number | undefined;
+  /**
+   * Per-connection MONITOR watchlist ceiling, advertised as `MONITOR=<n>`
+   * in `005 RPL_ISUPPORT`. Omitted → the reducer falls back to
+   * {@link DEFAULT_MONITOR_LIMIT} (the monitor cap's built-in ceiling).
+   *
+   * Typed `number | undefined` to mirror Zod's optional output shape under
+   * `exactOptionalPropertyTypes: true`.
+   */
+  readonly monitorLimit?: number | undefined;
+  /**
+   * Extended-ban prefix sigil advertised as `EXTBAN=<prefix>,…` in
+   * `005 RPL_ISUPPORT`. Omitted → defaults to `~` (the IRC-standard
+   * extban prefix).
+   *
+   * Typed `string | undefined` to mirror Zod's optional output shape under
+   * `exactOptionalPropertyTypes: true`.
+   */
+  readonly extbanPrefix?: string | undefined;
+  /**
+   * Whether IRC services (NickServ/ChanServ) are wired up for this
+   * deployment. When true, `005 RPL_ISUPPORT` advertises `ACCOUNTEXTBAN=a`
+   * (account-name extended bans), which are only meaningful once nicks are
+   * registered. Omitted/false → the token is suppressed until services
+   * ship.
+   *
+   * Typed `boolean | undefined` to mirror Zod's optional output shape under
+   * `exactOptionalPropertyTypes: true`.
+   */
+  readonly servicesEnabled?: boolean | undefined;
 }
 
 /** Per-invocation context handed to every reducer. */
@@ -162,10 +230,43 @@ export interface Ctx {
    * entries and the WHOWAS reducer replays them.
    */
   readonly history?: NickHistoryStore;
+  /**
+   * Read-marker persistence source for IRCv3 `draft/read-marker` (absent
+   * when the deployment does not persist read markers). When present, a
+   * `+draft/read-marker=<msgid>` TAGMSG from an identified, cap-enabled
+   * client updates the per-`(account, channel)` marker, and SASL identify
+   * seeds the connection's `lastReadMarkers` from the stored values so a
+   * reconnect restores the user's read position.
+   */
+  readonly readMarkers?: ReadMarkerStore;
+  /**
+   * Away-status persistence source for IRCv3 `draft/pre-away` (absent
+   * when the deployment does not persist away reasons). When present, a
+   * set/clear of `AWAY` from an identified connection mirrors the change
+   * into the per-`account` record, and SASL identify replays the stored
+   * reason onto the connection (emitting `306 RPL_NOWAWAY`) so a
+   * reconnect restores the user's away state. Omitted (→ `ctx.away`
+   * undefined) preserves the session-only behaviour: the connection
+   * still tracks its own `AWAY` but the reason is not shared across
+   * connections or restored on reconnect.
+   */
+  readonly away?: AwayStore;
   /** The connection invoking the command. Reducers mutate this freely. */
   readonly connection: ConnectionState;
   /** Convenience: `connection.id`. */
   readonly connId: string;
+  /**
+   * IRCv3 `labeled-response` label carried by the inbound message (the value
+   * of the `+label` client tag), or `undefined` when the request was
+   * unlabeled. Plumbed through ctx so every reducer's emitted effects are
+   * uniformly attributable to the labeled request; the actor layer wraps the
+   * requester's replies in one `BATCH +label labeled-response … -label` frame
+   * (or emits an empty batch when there is no reply).
+   *
+   * Typed `string | undefined` to mirror the optional-output shape under
+   * `exactOptionalPropertyTypes: true`.
+   */
+  readonly label?: string | undefined;
 }
 
 /** Result of a single reducer invocation. */
@@ -190,7 +291,15 @@ export interface BuildCtxOptions {
   mtlsIdentity?: MtlsIdentityProvider;
   messages?: MessageStore;
   history?: NickHistoryStore;
+  readMarkers?: ReadMarkerStore;
+  away?: AwayStore;
   connection: ConnectionState;
+  /**
+   * IRCv3 `labeled-response` label extracted from the inbound `+label` tag.
+   * Omitted (→ `ctx.label` undefined) when the request was unlabeled. See
+   * {@link Ctx.label}.
+   */
+  readonly label?: string | undefined;
 }
 
 /** Constructs a {@link Ctx} from the required parts. */
@@ -208,6 +317,9 @@ export function buildCtx(opts: BuildCtxOptions): Ctx {
     ...(opts.mtlsIdentity !== undefined ? { mtlsIdentity: opts.mtlsIdentity } : {}),
     ...(opts.messages !== undefined ? { messages: opts.messages } : {}),
     ...(opts.history !== undefined ? { history: opts.history } : {}),
+    ...(opts.readMarkers !== undefined ? { readMarkers: opts.readMarkers } : {}),
+    ...(opts.away !== undefined ? { away: opts.away } : {}),
+    ...(opts.label !== undefined ? { label: opts.label } : {}),
   };
   return ctx;
 }

package/packages/irc-core/stryker.commands.conf.json

@@ -36,6 +36,5 @@
   },
   "reporters": ["clear-text", "html"],
   "timeoutMS": 5000,
-  "concurrency": 2,
-  "ignoreStatic": true
+  "concurrency": 2
 }

package/packages/irc-core/tests/away-store.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { type AwayStore, InMemoryAwayStore } from '../src/ports';
+
+describe('InMemoryAwayStore — port conformance', () => {
+  it('implements the AwayStore port', () => {
+    const store: AwayStore = new InMemoryAwayStore();
+    expect(store).toBeDefined();
+  });
+});
+
+describe('InMemoryAwayStore — get / set / clear', () => {
+  it('returns undefined for an unknown account', () => {
+    const store = new InMemoryAwayStore();
+    expect(store.get('alice')).toBeUndefined();
+  });
+
+  it('stores and returns the away reason for a known account', () => {
+    const store = new InMemoryAwayStore();
+    store.set('alice', 'brb');
+    expect(store.get('alice')).toBe('brb');
+  });
+
+  it('overwrites the reason on a subsequent set for the same account', () => {
+    const store = new InMemoryAwayStore();
+    store.set('alice', 'brb');
+    store.set('alice', 'lunch');
+    expect(store.get('alice')).toBe('lunch');
+  });
+
+  it('keys accounts case-insensitively (rfc1459 fold)', () => {
+    const store = new InMemoryAwayStore();
+    store.set('Alice', 'brb');
+    expect(store.get('alice')).toBe('brb');
+    expect(store.get('ALICE')).toBe('brb');
+  });
+
+  it('keeps reasons for distinct accounts separate', () => {
+    const store = new InMemoryAwayStore();
+    store.set('alice', 'brb');
+    store.set('bob', 'afk');
+    expect(store.get('alice')).toBe('brb');
+    expect(store.get('bob')).toBe('afk');
+  });
+
+  it('clears the reason for an account on clear', () => {
+    const store = new InMemoryAwayStore();
+    store.set('alice', 'brb');
+    store.clear('alice');
+    expect(store.get('alice')).toBeUndefined();
+  });
+
+  it('is a no-op to clear an account that has no stored reason', () => {
+    const store = new InMemoryAwayStore();
+    store.clear('alice');
+    expect(store.get('alice')).toBeUndefined();
+  });
+
+  it('clears only the named account, leaving others intact', () => {
+    const store = new InMemoryAwayStore();
+    store.set('alice', 'brb');
+    store.set('bob', 'afk');
+    store.clear('alice');
+    expect(store.get('alice')).toBeUndefined();
+    expect(store.get('bob')).toBe('afk');
+  });
+
+  it('folds the account name case-insensitively on clear', () => {
+    const store = new InMemoryAwayStore();
+    store.set('Alice', 'brb');
+    store.clear('ALICE');
+    expect(store.get('alice')).toBeUndefined();
+  });
+});

package/packages/irc-core/tests/batch.test.ts

@@ -34,6 +34,21 @@ describe('wrapBatch — framing', () => {
     expect(out).toEqual<RawLine[]>([]);
   });
 
+  it('returns an empty BatchFrame carrying the framing metadata when lines is empty', () => {
+    // Empty batches are spec-forbidden and silently elided, but the returned
+    // array still advertises the id/type/start/body/end surface so callers
+    // can read the framing shape without a special-case branch.
+    const empty = wrapBatch([], 'ref7', 'chathistory', '#foo');
+    expect(empty).toHaveLength(0);
+    expect(empty.id).toBe('ref7');
+    expect(empty.type).toBe('chathistory');
+    expect(empty.start).toEqual({ text: '' });
+    expect(empty.body).toEqual([]);
+    expect(empty.end).toEqual({ text: '' });
+    // Non-enumerable props must not leak into JSON serialization.
+    expect(JSON.stringify(empty)).toBe('[]');
+  });
+
   it('preserves the order of the inner lines', () => {
     const lines = [L('one'), L('two'), L('three'), L('four')];
     const out = wrapBatch(lines, 'x', 'test');