@cosmicdrift/kumiko-framework 0.1.0

package/src/event-store/snapshot.ts

@@ -0,0 +1,210 @@
+import { and, desc, eq, sql } from "drizzle-orm";
+import type { DbConnection, DbRunner } from "../db/connection";
+import {
+  index,
+  instant,
+  integer,
+  jsonb,
+  table as pgTable,
+  primaryKey,
+  text,
+  uuid,
+} from "../db/dialect";
+import { tableExists } from "../db/schema-inspection";
+import type { TenantId } from "../engine/types";
+import { pushTables } from "../stack";
+import { isStreamArchived } from "./archive";
+import { loadEventsAfterVersion, type StoredEvent } from "./event-store";
+
+// Marten-aligned snapshot store. A snapshot is a point-in-time materialised
+// state of an aggregate at a specific version, cached so rehydrating the
+// aggregate doesn't require replaying every historical event.
+//
+// Read path (loadAggregateWithSnapshot):
+//   1. isStreamArchived? → honour same semantics as loadAggregate
+//   2. loadLatestSnapshot → state + version N (or null)
+//   3. loadEventsAfterVersion(aggregate, N) → only the delta
+//   4. reducer(snapshot, delta) → current state
+//
+// Write path: feature authors opt in via ctx.snapshotAggregate. Policy
+// (every N events, every M minutes, on-demand) is a feature-level decision
+// — the framework only offers the storage primitive.
+//
+// Schema-migration policy: NO built-in snapshot versioning. A snapshot stores
+// the aggregate state in the reducer's current shape. When the reducer's
+// shape changes (added field, renamed property, moved compound), invalidate
+// the cache — DELETE from kumiko_snapshots WHERE aggregate_type = '...'.
+// The read path then falls back to full replay (which runs the upcaster
+// chain on events) until the next snapshotAggregate call. Cheaper than a
+// second migration mechanism; snapshots are a perf optimisation, not a
+// source of truth.
+//
+// Upcaster interaction: the raw API (loadAggregateWithSnapshot below) does
+// NOT apply the upcaster chain on delta events — same layering as raw
+// loadAggregate. The Dispatcher wraps this into ctx.loadAggregateWithSnapshot
+// and runs upcastStoredEvents on the delta before calling the reducer, so
+// feature authors always see current-version payloads.
+
+export const snapshotsTable = pgTable(
+  "kumiko_snapshots",
+  {
+    aggregateId: uuid("aggregate_id").notNull(),
+    tenantId: uuid("tenant_id").notNull(),
+    // Kept even though (aggregate_id, version) is globally unique: the
+    // schema-migration invalidation mechanism (see file header) filters by
+    // aggregate_type, so storing it avoids a join on events just to
+    // invalidate snapshots.
+    aggregateType: text("aggregate_type").notNull(),
+    // The version covered by this snapshot. `loadEventsAfterVersion`
+    // returns events with version > this value.
+    version: integer("version").notNull(),
+    state: jsonb("state").$type<Record<string, unknown>>().notNull(),
+    createdAt: instant("created_at", { precision: 3 }).notNull().default(sql`now()`),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.aggregateId, t.version] }),
+    // Latest-snapshot lookup: WHERE aggregate_id = ? ORDER BY version DESC
+    // LIMIT 1. With this index the planner does one seek + backward scan
+    // instead of sort-and-limit.
+    latestIdx: index("kumiko_snapshots_latest_idx").on(t.aggregateId, t.tenantId, t.version),
+  }),
+);
+
+export async function createSnapshotsTable(db: DbConnection): Promise<void> {
+  // skip: table already exists — idempotent boot + test-setup call
+  if (await tableExists(db, "public.kumiko_snapshots")) return;
+  await pushTables(db, { kumikoSnapshots: snapshotsTable });
+}
+
+export type Snapshot<TState extends Record<string, unknown> = Record<string, unknown>> = {
+  readonly aggregateId: string;
+  readonly tenantId: TenantId;
+  readonly aggregateType: string;
+  readonly version: number;
+  readonly state: TState;
+  readonly createdAt: Temporal.Instant;
+};
+
+export type SaveSnapshotArgs = {
+  readonly aggregateId: string;
+  readonly tenantId: TenantId;
+  readonly aggregateType: string;
+  readonly version: number;
+  readonly state: Record<string, unknown>;
+};
+
+// Upsert-style save so re-snapshotting the same (aggregateId, version) is
+// idempotent. Caller can retake a snapshot at the same version without
+// bespoke error handling — useful when a feature's snapshot policy runs
+// during a concurrent retake.
+export async function saveSnapshot(db: DbRunner, args: SaveSnapshotArgs): Promise<void> {
+  await db
+    .insert(snapshotsTable)
+    .values({
+      aggregateId: args.aggregateId,
+      tenantId: args.tenantId,
+      aggregateType: args.aggregateType,
+      version: args.version,
+      state: args.state,
+    })
+    .onConflictDoUpdate({
+      target: [snapshotsTable.aggregateId, snapshotsTable.version],
+      set: {
+        state: args.state,
+        aggregateType: args.aggregateType,
+        createdAt: sql`now()`,
+      },
+    });
+}
+
+// Latest snapshot lookup. Tenant filter is belt-and-suspenders — the
+// aggregate_id should already scope uniquely, but an accidentally-reused
+// UUID across tenants would otherwise silently leak.
+export async function loadLatestSnapshot<
+  TState extends Record<string, unknown> = Record<string, unknown>,
+>(db: DbRunner, aggregateId: string, tenantId: TenantId): Promise<Snapshot<TState> | null> {
+  const rows = await db
+    .select()
+    .from(snapshotsTable)
+    .where(and(eq(snapshotsTable.aggregateId, aggregateId), eq(snapshotsTable.tenantId, tenantId)))
+    .orderBy(desc(snapshotsTable.version))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return null;
+  return {
+    aggregateId: row.aggregateId,
+    tenantId: row.tenantId,
+    aggregateType: row.aggregateType,
+    version: row.version,
+    state: row.state as TState,
+    createdAt: row.createdAt,
+  };
+}
+
+// Reducer used to fold events onto a state. Kept narrow and pure — the
+// caller supplies the shape and update rules. Mirrors the reducer shape
+// feature authors already write for r.projection.apply.
+export type SnapshotReducer<TState extends Record<string, unknown>> = (
+  state: TState,
+  event: StoredEvent,
+) => TState;
+
+export type LoadAggregateWithSnapshotResult<TState extends Record<string, unknown>> = {
+  readonly state: TState;
+  readonly version: number;
+  readonly snapshotHit: boolean;
+};
+
+export type LoadAggregateWithSnapshotOptions = {
+  // Opt-in: include archived streams in the rehydrate. Default false — same
+  // semantics as loadAggregate / loadAggregateAsOf. Archive check is a
+  // single indexed lookup, so the cost stays negligible on the hot path.
+  readonly includeArchived?: boolean;
+  // Optional upcaster step: every delta event goes through this transform
+  // BEFORE the reducer sees it. The dispatcher wires this up with
+  // r.eventMigration so feature code always sees current-version payloads.
+  // Async to support Marten-style AsyncOnlyEventUpcaster (DB lookups).
+  readonly upcastEvent?: (event: StoredEvent) => Promise<StoredEvent>;
+};
+
+// Snapshot-aware rehydrate. Loads the latest snapshot (if any), applies
+// events strictly newer than snapshot.version, and returns the fold.
+// Callers that want strictly-event-sourced loading should stick with
+// loadAggregate + reduce — this path exists for perf-critical aggregates.
+//
+// Archive behaviour mirrors loadAggregate: an archived stream returns
+// `initial` with version=0, snapshotHit=false, unless
+// { includeArchived: true } is passed. This keeps snapshot and raw
+// loadAggregate interchangeable from the caller's point of view.
+export async function loadAggregateWithSnapshot<TState extends Record<string, unknown>>(
+  db: DbRunner,
+  aggregateId: string,
+  tenantId: TenantId,
+  reducer: SnapshotReducer<TState>,
+  initial: TState,
+  options?: LoadAggregateWithSnapshotOptions,
+): Promise<LoadAggregateWithSnapshotResult<TState>> {
+  if (!options?.includeArchived) {
+    const archived = await isStreamArchived(db, tenantId, aggregateId);
+    if (archived) {
+      return { state: initial, version: 0, snapshotHit: false };
+    }
+  }
+  const snapshot = await loadLatestSnapshot<TState>(db, aggregateId, tenantId);
+  const baseState = snapshot ? snapshot.state : initial;
+  const afterVersion = snapshot ? snapshot.version : 0;
+  const delta = await loadEventsAfterVersion(db, aggregateId, tenantId, afterVersion);
+
+  let state = baseState;
+  for (const event of delta) {
+    const effective = options?.upcastEvent ? await options.upcastEvent(event) : event;
+    state = reducer(state, effective);
+  }
+  const lastDelta = delta[delta.length - 1];
+  const latestVersion = lastDelta ? lastDelta.version : afterVersion;
+  return {
+    state,
+    version: latestVersion,
+    snapshotHit: snapshot !== null,
+  };
+}

package/src/event-store/upcaster-dead-letter.ts

@@ -0,0 +1,119 @@
+// Dead-letter storage for failed event upcasters.
+//
+// Background: upcastStoredEvent walks a stored event's payload through
+// r.eventMigration transforms until it matches the current schema. A
+// migration that throws (malformed legacy payload, DB-dependent
+// enrichment that fails) propagates to the dispatcher and kills the
+// pass — one bad event in a million can stall every projection behind
+// it. The same applies to MSP rebuild.
+//
+// Quarantine mode captures the failure into `kumiko_upcaster_dead_letters`,
+// lets the dispatcher skip the event, and surfaces the row count via
+// ops tooling. Replay (re-apply the migration after a code fix) is a
+// separate CLI step — not implemented here, tracked as follow-up.
+
+import { bigint, index, integer, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import type { DbConnection, DbRunner } from "../db/connection";
+import { tableExists } from "../db/schema-inspection";
+import { pushTables } from "../stack";
+import type { StoredEvent } from "./event-store";
+
+export const upcasterDeadLetterTable = pgTable(
+  "kumiko_upcaster_dead_letters",
+  {
+    // Surrogate PK. We don't reuse eventId so a single event can land
+    // here multiple times (retry attempts across deploys before the fix
+    // lands) without unique-violation noise.
+    id: bigint("id", { mode: "bigint" }).primaryKey().generatedAlwaysAsIdentity(),
+    // StoredEvent.id is surfaced as `string` (bigint serialised for JSON
+    // safety). Storing as text keeps the round-trip identity without a
+    // coerce step at every write site.
+    eventId: text("event_id").notNull(),
+    tenantId: uuid("tenant_id").notNull(),
+    aggregateId: text("aggregate_id").notNull(),
+    aggregateType: text("aggregate_type").notNull(),
+    eventType: text("event_type").notNull(),
+    fromVersion: integer("from_version").notNull(),
+    targetVersion: integer("target_version").notNull(),
+    errorMessage: text("error_message").notNull(),
+    originalPayload: jsonb("original_payload").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    eventTypeIdx: index("upcaster_dead_letters_event_type_idx").on(t.eventType),
+    createdAtIdx: index("upcaster_dead_letters_created_at_idx").on(t.createdAt),
+  }),
+);
+
+// Idempotent table-create. Called from setupTestStack for suites that
+// exercise the quarantine path; production boot uses drizzle-kit push.
+export async function createUpcasterDeadLetterTable(db: DbConnection): Promise<void> {
+  // skip: table already exists — bootstrap called from multiple paths
+  if (await tableExists(db, "public.kumiko_upcaster_dead_letters")) return;
+  await pushTables(db, { kumikoUpcasterDeadLetters: upcasterDeadLetterTable });
+}
+
+// Writes a dead-letter row. Called by upcastStoredEvent when errorPolicy
+// is "quarantine" and a transform threw. Returns the inserted row id —
+// ops tooling uses it for correlate-and-replay flows.
+export async function recordUpcasterDeadLetter(
+  db: DbRunner,
+  args: {
+    event: StoredEvent;
+    fromVersion: number;
+    targetVersion: number;
+    error: unknown;
+  },
+): Promise<void> {
+  const message = args.error instanceof Error ? args.error.message : String(args.error);
+  await db.insert(upcasterDeadLetterTable).values({
+    eventId: args.event.id,
+    tenantId: args.event.tenantId,
+    aggregateId: args.event.aggregateId,
+    aggregateType: args.event.aggregateType,
+    eventType: args.event.type,
+    fromVersion: args.fromVersion,
+    targetVersion: args.targetVersion,
+    errorMessage: message,
+    originalPayload: args.event.payload,
+  });
+}
+
+export type DeadLetterRow = {
+  readonly id: bigint;
+  readonly eventId: string;
+  readonly tenantId: string;
+  readonly aggregateId: string;
+  readonly aggregateType: string;
+  readonly eventType: string;
+  readonly fromVersion: number;
+  readonly targetVersion: number;
+  readonly errorMessage: string;
+  readonly originalPayload: Record<string, unknown>;
+  readonly createdAt: Date;
+};
+
+// Ops-side query. Loads recent failures, optionally scoped by event-type
+// to triage a single broken migration without pulling the full table.
+export async function listDeadLetters(
+  db: DbConnection,
+  options: { eventType?: string; limit?: number } = {},
+): Promise<readonly DeadLetterRow[]> {
+  const { desc, eq } = await import("drizzle-orm");
+  const limit = options.limit ?? 100;
+  const eventType = options.eventType;
+  const rows =
+    eventType !== undefined
+      ? await db
+          .select()
+          .from(upcasterDeadLetterTable)
+          .where(eq(upcasterDeadLetterTable.eventType, eventType))
+          .orderBy(desc(upcasterDeadLetterTable.createdAt))
+          .limit(limit)
+      : await db
+          .select()
+          .from(upcasterDeadLetterTable)
+          .orderBy(desc(upcasterDeadLetterTable.createdAt))
+          .limit(limit);
+  return rows as readonly DeadLetterRow[];
+}

package/src/event-store/upcaster.ts

@@ -0,0 +1,147 @@
+import type { DbRunner } from "../db";
+import type { EventUpcastCtx, EventUpcastFn, TenantId } from "../engine/types";
+import type { StoredEvent } from "./event-store";
+import { recordUpcasterDeadLetter } from "./upcaster-dead-letter";
+
+// Error-handling contract for the upcast pass.
+//
+//   throw     — legacy behaviour: the pass aborts, the dispatcher retries,
+//               a permanently broken payload eventually dead-letters at
+//               the consumer level after maxAttempts retries. Pick this
+//               when every event must land exactly once and "skip" is
+//               never acceptable.
+//
+//   quarantine — the failing event is written to
+//               `kumiko_upcaster_dead_letters` with the error + original
+//               payload and REMOVED from the returned list. The
+//               dispatcher skips it cleanly; ops tooling replays after
+//               the code fix. Pick this for projections where a single
+//               unrenderable historic event shouldn't block the rest
+//               of the stream.
+export type UpcasterErrorPolicy = "throw" | "quarantine";
+
+export type UpcastOptions = {
+  readonly errorPolicy?: UpcasterErrorPolicy;
+};
+
+// Event schema evolution (Marten-style upcaster). An event's stored payload
+// stays immutable on disk; when a feature bumps the event version and
+// registers step-wise r.eventMigration transforms, reads walk older events
+// through the chain until the payload matches the current shape.
+//
+// Sync transforms cost O(version_gap) plain JSON rewrites — hot path on
+// projection rebuild stays cheap. Async transforms (Marten's
+// AsyncOnlyEventUpcaster) for DB-enrichment are supported via the same
+// signature: return Promise<unknown>, the framework awaits unconditionally.
+// Sync transforms still pay only the await-microtask overhead.
+
+export type EventUpcasters = ReadonlyMap<
+  string,
+  { readonly currentVersion: number; readonly chain: ReadonlyMap<number, EventUpcastFn> }
+>;
+
+// Upcast a single stored event through however many registered migrations
+// separate its stored eventVersion from the current schema version.
+//
+// Contract:
+//   - Event types with no registered upcaster pass through unchanged.
+//   - Event types whose stored version equals currentVersion pass through
+//     unchanged (fast path — hot on projection rebuild).
+//   - Gaps in the chain are a hard error. The registry validates chain
+//     completeness at boot, so this throw is a belt-and-suspenders signal
+//     that something wrote a version number the registry doesn't expect.
+//
+// `ctx` carries db + tenantId for async upcasters that need DB enrichment.
+// Sync transforms ignore ctx entirely.
+// Legacy throw-on-error API — preserved so existing callers (projection-
+// rebuild, msp-rebuild, feature tests) stay unchanged. Returns a
+// StoredEvent (never null); quarantine mode lives on the bulk helper.
+export async function upcastStoredEvent(
+  event: StoredEvent,
+  upcasters: EventUpcasters,
+  ctx: EventUpcastCtx,
+): Promise<StoredEvent> {
+  const result = await upcastStoredEventWithPolicy(event, upcasters, ctx, {
+    errorPolicy: "throw",
+  });
+  // `throw` mode can never return null — the catch-block rethrows. Narrow
+  // the type for callers without an `if (result === null)` check at every
+  // callsite.
+  if (result === null) {
+    throw new Error(
+      `unreachable: upcastStoredEvent with errorPolicy="throw" returned null for "${event.type}"`,
+    );
+  }
+  return result;
+}
+
+// Underlying policy-aware worker. Returns null when the transform threw
+// AND errorPolicy="quarantine" — the event gets recorded in dead-letters
+// and the bulk helper filters it out.
+async function upcastStoredEventWithPolicy(
+  event: StoredEvent,
+  upcasters: EventUpcasters,
+  ctx: EventUpcastCtx,
+  options: UpcastOptions,
+): Promise<StoredEvent | null> {
+  const info = upcasters.get(event.type);
+  if (!info) return event;
+  if (event.eventVersion >= info.currentVersion) return event;
+
+  let payload = event.payload as unknown;
+  let v = event.eventVersion;
+  const startVersion = event.eventVersion;
+  while (v < info.currentVersion) {
+    const transform = info.chain.get(v);
+    if (!transform) {
+      // Missing chain is a boot-validator bug, not a data problem —
+      // always throw regardless of policy so the gap gets fixed rather
+      // than silently rotting every affected event into dead-letters.
+      throw new Error(
+        `Missing upcaster for event "${event.type}" v${v} → v${v + 1}. ` +
+          `The registry should have caught this at boot — check the eventUpcasterMap wiring.`,
+      );
+    }
+    try {
+      payload = await transform(payload, ctx);
+      v++;
+    } catch (err) {
+      if (options.errorPolicy === "quarantine") {
+        await recordUpcasterDeadLetter(ctx.db, {
+          event,
+          fromVersion: startVersion,
+          targetVersion: info.currentVersion,
+          error: err,
+        });
+        return null;
+      }
+      throw err;
+    }
+  }
+  return {
+    ...event,
+    payload: payload as Record<string, unknown>, // @cast-boundary engine-payload
+    eventVersion: v,
+  };
+}
+
+export async function upcastStoredEvents(
+  events: readonly StoredEvent[],
+  upcasters: EventUpcasters,
+  ctx: EventUpcastCtx,
+  options: UpcastOptions = {},
+): Promise<readonly StoredEvent[]> {
+  // skip: no upcasters registered anywhere — common case when a project
+  // hasn't bumped any event version yet. Short-circuit keeps replay fast.
+  if (upcasters.size === 0) return events;
+  const results = await Promise.all(
+    events.map((e) => upcastStoredEventWithPolicy(e, upcasters, ctx, options)),
+  );
+  return results.filter((e): e is StoredEvent => e !== null);
+}
+
+// Convenience builder for callers that have db + tenantId at hand and want
+// to construct the ctx-arg without restating the field names everywhere.
+export function makeUpcastCtx(db: DbRunner, tenantId: TenantId): EventUpcastCtx {
+  return { db, tenantId };
+}

package/src/files/__tests__/content-disposition.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "vitest";
+import {
+  buildContentDispositionHeader,
+  encodeRFC5987,
+  toAsciiFallback,
+} from "../content-disposition";
+
+describe("toAsciiFallback", () => {
+  test("keeps ASCII letters, digits, dot, dash, underscore, parens", () => {
+    expect(toAsciiFallback("photo_2024-01.png")).toBe("photo_2024-01.png");
+    expect(toAsciiFallback("report(v2).pdf")).toBe("report(v2).pdf");
+  });
+
+  test("collapses spaces, commas, and other non-safe chars to underscore", () => {
+    expect(toAsciiFallback("my photo, v2.png")).toBe("my_photo__v2.png");
+  });
+
+  test("strips quote characters — the core injection protection", () => {
+    const evil = `safe.png"; filename*=utf-8''evil.exe`;
+    const out = toAsciiFallback(evil);
+    expect(out).not.toContain('"');
+    expect(out).not.toContain(";");
+  });
+
+  test("strips backslash and path separators (directory-traversal guard)", () => {
+    // Dots survive (whitelisted); `/` and `\` collapse to underscore.
+    expect(toAsciiFallback("../../../etc/passwd")).toBe(".._.._.._etc_passwd");
+    expect(toAsciiFallback("C:\\Windows\\evil.exe")).toBe("C__Windows_evil.exe");
+  });
+
+  test("collapses non-ASCII (unicode) to underscore — one char per code unit", () => {
+    // 測 + 試 = 2 BMP code units → 2 underscores, then `.png` passes through.
+    expect(toAsciiFallback("測試.png")).toBe("__.png");
+    expect(toAsciiFallback("café.pdf")).toBe("caf_.pdf");
+  });
+
+  test("truncates at 100 chars to bound header size", () => {
+    const longName = `${"a".repeat(200)}.png`;
+    const out = toAsciiFallback(longName);
+    expect(out.length).toBe(100);
+    expect(out.startsWith("aaaa")).toBe(true);
+  });
+
+  test("returns 'download' for empty input or when no alphanumerics survive", () => {
+    // Empty stripped.
+    expect(toAsciiFallback("")).toBe("download");
+    // All non-safe chars collapsed → 12 underscores → readable default.
+    expect(toAsciiFallback("@@@###$$$%%%")).toBe("download");
+    // Mix of symbols + dots (dots whitelisted) → still no alphanumerics.
+    expect(toAsciiFallback("@.#.$")).toBe("download");
+  });
+});
+
+describe("encodeRFC5987", () => {
+  test("passes pure ASCII through (letters, digits)", () => {
+    expect(encodeRFC5987("photo.png")).toBe("photo.png");
+  });
+
+  test("percent-encodes UTF-8 bytes for non-ASCII", () => {
+    // 測 = UTF-8 E6 B8 AC → %E6%B8%AC
+    const out = encodeRFC5987("測");
+    expect(out).toBe("%E6%B8%AC");
+  });
+
+  test("escapes the RFC-5987 extras that encodeURIComponent leaves alone", () => {
+    // encodeURIComponent doesn't escape ' ( ) * — RFC 5987 requires we do.
+    // Each char maps to its uppercase hex code.
+    expect(encodeRFC5987("a'b")).toBe("a%27b");
+    expect(encodeRFC5987("a(b)")).toBe("a%28b%29");
+    expect(encodeRFC5987("a*b")).toBe("a%2Ab");
+  });
+
+  test("uses uppercase hex for consistency (matches RFC sample output)", () => {
+    expect(encodeRFC5987(" ")).toBe("%20");
+    expect(encodeRFC5987(";")).toBe("%3B");
+  });
+});
+
+describe("buildContentDispositionHeader", () => {
+  test("pure ASCII input produces both parameters", () => {
+    const header = buildContentDispositionHeader("photo.png");
+    expect(header).toBe(`attachment; filename="photo.png"; filename*=UTF-8''photo.png`);
+  });
+
+  test("unicode input survives losslessly in filename*, stripped in fallback", () => {
+    const header = buildContentDispositionHeader("測試.png");
+    // 2 BMP code units → 2 underscores in fallback, then `.png`.
+    expect(header).toContain(`filename="__.png"`);
+    // filename* carries the full UTF-8 bytes percent-encoded.
+    expect(header).toContain("filename*=UTF-8''%E6%B8%AC%E8%A9%A6.png");
+  });
+
+  test("injection attempt — header has exactly 3 semicolon-separated parts", () => {
+    // `"; filename*=utf-8''evil.exe` injection — sanitised header must
+    // still parse as a single attachment with exactly two parameters.
+    const header = buildContentDispositionHeader(`normal.png"; filename*=utf-8''evil.exe`);
+    const parts = header.split(";");
+    expect(parts).toHaveLength(3);
+    expect(parts[0]).toBe("attachment");
+    expect(parts[1]?.trim().startsWith("filename=")).toBe(true);
+    expect(parts[2]?.trim().startsWith("filename*=")).toBe(true);
+  });
+
+  test("fallback never leaks unquoted double-quote", () => {
+    // Any quote inside filename="..." would close the string early and
+    // let the tail parse as new parameters. Proof: the fallback value
+    // (the chars between the first two quotes after "filename=") has
+    // no further quotes.
+    const header = buildContentDispositionHeader(`a"b"c.png`);
+    const match = header.match(/filename="([^"]*)"/);
+    expect(match).not.toBeNull();
+    expect(match?.[1]).not.toContain('"');
+    // All 3 quotes collapsed to underscore in the fallback.
+    expect(match?.[1]).toBe("a_b_c.png");
+  });
+
+  test("empty filename falls back to 'download'", () => {
+    const header = buildContentDispositionHeader("");
+    expect(header).toContain(`filename="download"`);
+    // Empty filename*: encodeRFC5987("") → "", so filename*=UTF-8''
+    expect(header).toContain(`filename*=UTF-8''`);
+  });
+});