@freighttech/terminal-tracking 0.7.0

package/src/modules/terminal_tracking/lib/adapters/n4/http.ts

@@ -0,0 +1,127 @@
+import { fetch, type RequestInit as UndiciRequestInit } from 'undici'
+import { proxyDispatcher, type FetchInitWithDispatcher } from './proxy'
+import { terminalLogger } from '../../logger'
+
+/** Outcome of an N4 HTTP request: status + the fully-read response body. */
+export type N4Response = { status: number; ok: boolean; text: string }
+
+export type N4RequestOptions = {
+  /** Terminal proxy URL — egresses through an undici ProxyAgent when set. */
+  proxyUrl?: string | null
+  /** Per-attempt timeout (whole attempt: connect + headers + body). Default 30s. */
+  timeoutMs?: number
+  /** Extra attempts after the first, on transient network failures. Default 2. */
+  retries?: number
+  /** Base backoff between attempts (doubles each retry). Default 250ms. */
+  retryBackoffMs?: number
+  /** Short label for logs (e.g. `"<terminalCode> /unit"`). */
+  label?: string
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000
+const DEFAULT_RETRIES = 2
+const DEFAULT_BACKOFF_MS = 250
+
+// undici raises these for a dropped/half-open/timed-out connection — all safe to
+// retry (the request either never reached the server or got no usable response).
+const TRANSIENT_CODES = new Set([
+  'UND_ERR_SOCKET',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_HEADERS_TIMEOUT',
+  'UND_ERR_BODY_TIMEOUT',
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'EPIPE',
+  'ETIMEDOUT',
+  'EAI_AGAIN',
+])
+
+/**
+ * A transient network failure (connection dropped/reset/timed out) — distinct
+ * from an HTTP error *status*, which is a real answer and must not be retried.
+ */
+export function isTransientNetworkError(err: unknown): boolean {
+  // AbortSignal.timeout() rejects with a TimeoutError DOMException.
+  if (err instanceof DOMException && err.name === 'TimeoutError') return true
+  const e = err as { code?: string; message?: string; cause?: { code?: string; message?: string } }
+  const code = e?.code ?? e?.cause?.code
+  if (code && TRANSIENT_CODES.has(code)) return true
+  // undici surfaces a mid-flight peer socket close as `TypeError: terminated`
+  // (cause: UND_ERR_SOCKET "other side closed"); match on message as a backstop.
+  const msg = `${e?.message ?? ''} ${e?.cause?.message ?? ''}`
+  return /terminated|other side closed|socket hang ?up|fetch failed/i.test(msg)
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
+
+/**
+ * Perform one N4 HTTP request and ALWAYS fully read the response body — even on a
+ * non-2xx status — returning `{ status, ok, text }`. Callers inspect `status`
+ * and parse `text`; they never touch the live response stream.
+ *
+ * Why drain the body unconditionally: undici holds the keep-alive socket open
+ * while a response body is unread. The previous code threw on a non-ok status
+ * (e.g. Baltic Hub's Cloudflare allowlist 403) WITHOUT reading the body, leaving
+ * a dangling stream. When the peer later closed that socket, undici errored the
+ * orphaned body controller with no reader attached, surfacing an *unhandled*
+ * `TypeError: terminated`. Under Node's default unhandled-rejection policy that
+ * killed the queue-worker process and took the whole server down. Reading the
+ * body inside this `try` means any mid-stream close rejects an awaited call here,
+ * where it is caught and (when transient) retried — it can never escape.
+ *
+ * Each attempt is bounded by an AbortSignal timeout, and transient connection
+ * drops are retried with exponential backoff so a single Cloudflare/tunnel
+ * keep-alive reset doesn't fail an entire poll cycle.
+ */
+export async function n4Request(
+  url: string,
+  init: Omit<FetchInitWithDispatcher, 'dispatcher' | 'signal'>,
+  options: N4RequestOptions = {},
+): Promise<N4Response> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const retries = options.retries ?? DEFAULT_RETRIES
+  const backoffMs = options.retryBackoffMs ?? DEFAULT_BACKOFF_MS
+  const dispatcher = proxyDispatcher(options.proxyUrl)
+  const label = options.label ?? url
+
+  let lastErr: unknown
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      // `fetch` is imported from undici (not the global) so the request driver
+      // and the `dispatcher` (a ProxyAgent from the SAME undici) belong to one
+      // instance. With the global fetch — Node's *built-in* undici — driving a
+      // dispatcher from this package's *bundled* undici, a peer socket reset
+      // makes the bundled dispatcher call the built-in fetch's onAborted, which
+      // throws `TypeError: terminated` from a detached socket-close handler that
+      // no try/catch here can see — it escaped as an uncaughtException and killed
+      // the worker. Same-instance, that reset rejects the awaited call below,
+      // where it is caught and (when transient) retried.
+      const res = await fetch(url, {
+        ...init,
+        dispatcher,
+        signal: AbortSignal.timeout(timeoutMs),
+      } as UndiciRequestInit)
+      // Drain the body within this try — see the doc comment above. This is the
+      // line that prevents the dangling-stream unhandled rejection.
+      const text = await res.text()
+      return { status: res.status, ok: res.ok, text }
+    } catch (err) {
+      lastErr = err
+      if (attempt < retries && isTransientNetworkError(err)) {
+        const wait = backoffMs * 2 ** attempt
+        terminalLogger.warn('N4 request transient failure — retrying', {
+          label,
+          attempt: attempt + 1,
+          maxAttempts: retries + 1,
+          waitMs: wait,
+          message: err instanceof Error ? err.message : String(err),
+        })
+        await sleep(wait)
+        continue
+      }
+      throw err
+    }
+  }
+  // The loop always returns or throws; this satisfies the type checker.
+  throw lastErr
+}

package/src/modules/terminal_tracking/lib/adapters/n4/n4-semantics.ts

@@ -0,0 +1,156 @@
+import type { N4UnitRow } from './types'
+import { DEFAULT_TERMINAL_TIMEZONE, zonedNaiveToUtc } from '../zoned-time'
+import type { TerminalFetchedEvent, ResolvedTerminalConfig } from '../../terminal-adapter'
+import type {
+  TerminalEventType,
+  TerminalEventClassifierCode,
+  TerminalModeOfTransport,
+} from '../../../data/entities'
+
+type StateMapping = {
+  code: string // canonical N4 transit-state code
+  eventType: TerminalEventType
+  eventCode: string
+  classifier: TerminalEventClassifierCode
+  timestampField: 'timeIn' | 'timeOut' | 'loaded'
+}
+
+/**
+ * Maps an N4 friendly T-State (as returned by `/unit`) to a normalized event.
+ * The `/unit` response uses friendly names ("Inbound", "Yard", "Loaded",
+ * "Departed"); the `S*` codes are the request-side filter values.
+ */
+const STATE_MAP: Record<string, StateMapping> = {
+  inbound: { code: 'S20_INBOUND', eventType: 'EQUIPMENT', eventCode: 'GTIN', classifier: 'ACT', timestampField: 'timeIn' },
+  ecin: { code: 'S30_ECIN', eventType: 'EQUIPMENT', eventCode: 'GTIN', classifier: 'ACT', timestampField: 'timeIn' },
+  yard: { code: 'S40_YARD', eventType: 'EQUIPMENT', eventCode: 'DISC', classifier: 'ACT', timestampField: 'timeIn' },
+  loaded: { code: 'S60_LOADED', eventType: 'EQUIPMENT', eventCode: 'LOAD', classifier: 'ACT', timestampField: 'loaded' },
+  departed: { code: 'S70_DEPARTED', eventType: 'TRANSPORT', eventCode: 'DEPA', classifier: 'ACT', timestampField: 'timeOut' },
+}
+
+/** Map an eventCode to the semantic module event id (or null if none). */
+export function semanticEventIdFor(eventCode: string): string | null {
+  switch (eventCode) {
+    case 'GTIN':
+      return 'terminal_tracking.equipment.gate_in'
+    case 'DISC':
+      return 'terminal_tracking.equipment.discharged'
+    case 'LOAD':
+      return 'terminal_tracking.equipment.loaded'
+    case 'DEPA':
+      return 'terminal_tracking.transport.departed'
+    default:
+      return null
+  }
+}
+
+export function buildSourceEventId(terminalCode: string, ufvGkey: string, eventCode: string): string {
+  return `${terminalCode}:${ufvGkey}:${eventCode}`
+}
+
+/**
+ * Parse an N4 timestamp ("yyyy-mm-dd hh:mm[:ss]"). N4 returns terminal-local
+ * time without an offset, so we interpret it in the terminal's timezone
+ * (Europe/Warsaw by default) and return the corresponding UTC instant.
+ */
+export function parseN4DateTime(
+  value: string | null | undefined,
+  timeZone: string = DEFAULT_TERMINAL_TIMEZONE,
+): Date | null {
+  if (!value) return null
+  const m = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/.exec(value.trim())
+  if (!m) return null
+  const [, yyyy, mm, dd, hh, mi, ss] = m
+  return zonedNaiveToUtc(+yyyy, +mm, +dd, +hh, +mi, ss ? +ss : 0, timeZone)
+}
+
+export function inferMode(visitRef: string | null | undefined): TerminalModeOfTransport | null {
+  if (!visitRef) return null
+  const v = visitRef.toUpperCase()
+  if (v.includes('TRUCK')) return 'TRUCK'
+  // Rail visit ids look like 'TUX3W31-25_IMP' / '..._EXP'
+  if (/_IMP|_EXP|\bW\d/.test(v)) return 'RAIL'
+  return 'VESSEL'
+}
+
+/**
+ * The container's direction of travel through the terminal, from the N4
+ * `Category` column. Anything else N4 reports (notably "Storage" for empties)
+ * is not a direction and normalizes to null.
+ */
+export type TerminalCargoCategory = 'import' | 'export'
+
+/** Normalize an N4 `Category` value to a direction (null when not directional). */
+export function parseCargoCategory(rawData: Record<string, unknown> | null | undefined): TerminalCargoCategory | null {
+  const category = String(rawData?.['Category'] ?? '').trim().toLowerCase()
+  if (category === 'import') return 'import'
+  if (category === 'export') return 'export'
+  return null
+}
+
+/**
+ * Pick the vessel-side visit ref for a leg, by its N4 `Category`:
+ * an **Import** leg's vessel is the inbound visit ("I/B Actual Visit"); an
+ * **Export** leg's vessel is the outbound visit ("O/B Actual Visit"). The `dir`
+ * tells the caller which voyage (inbound vs outbound) to attach. Returns null
+ * when the category is unknown or the relevant side is missing.
+ */
+export function pickVesselVisit(
+  event: Pick<TerminalFetchedEvent, 'visitRefIn' | 'visitRefOut' | 'rawData'>,
+): { ref: string; dir: 'in' | 'out' } | null {
+  const category = parseCargoCategory(event.rawData)
+  if (category === 'import') return event.visitRefIn ? { ref: event.visitRefIn, dir: 'in' } : null
+  if (category === 'export') return event.visitRefOut ? { ref: event.visitRefOut, dir: 'out' } : null
+  return null
+}
+
+/**
+ * Map a single N4 unit-facility-visit row to a normalized terminal event,
+ * keyed by the row's current transit state. Returns null when the state is not
+ * mappable (e.g. advised-only, retired).
+ */
+export function mapRowToEvent(
+  row: N4UnitRow,
+  config: ResolvedTerminalConfig,
+): TerminalFetchedEvent | null {
+  const stateKey = (row.tState ?? '').trim().toLowerCase()
+  const mapping = STATE_MAP[stateKey]
+  if (!mapping) return null
+
+  const eventDateTime =
+    parseN4DateTime(row[mapping.timestampField]) ??
+    parseN4DateTime(row.timeOut) ??
+    parseN4DateTime(row.loaded) ??
+    parseN4DateTime(row.timeIn) ??
+    new Date()
+
+  const seals = (row.seals ?? []).map((number) => ({ number, source: config.terminalCode }))
+
+  return {
+    source: 'terminal',
+    sourceEventId: buildSourceEventId(config.terminalCode, row.ufvGkey, mapping.eventCode),
+    eventType: mapping.eventType,
+    eventCode: mapping.eventCode,
+    eventClassifierCode: mapping.classifier,
+    eventDateTime,
+    containerNumber: row.unitNbr,
+    ufvGkey: row.ufvGkey,
+    transitState: mapping.code,
+    visitState: row.vState ?? null,
+    facilityCode: config.facilityCode ?? null,
+    facilityCodeListProvider: config.facilityCodeListProvider ?? null,
+    unlocode: config.unlocode ?? null,
+    visitRefIn: row.ibActualVisit ?? null,
+    visitRefOut: row.obActualVisit ?? null,
+    vesselName: null,
+    voyageNumber: null,
+    modeOfTransport: inferMode(row.obActualVisit) ?? inferMode(row.ibActualVisit),
+    seals: seals.length ? seals : null,
+    vgmWeightKg: row.vgmWeight ?? null,
+    impediments: row.impediments ?? null,
+    // The N4 `Loaded` timestamp, parsed independently of the current state so a
+    // container that has since departed still carries when it was loaded.
+    loadedAt: parseN4DateTime(row.loaded),
+    rawData: row.raw,
+  }
+}

package/src/modules/terminal_tracking/lib/adapters/n4/parsers/data-table.ts

@@ -0,0 +1,102 @@
+import type { N4UnitRow } from '../types'
+import { parseTerminalStops } from '../../../stops'
+
+/** Coerce a value that may be a single item or an array into an array. */
+function asArray<T>(v: T | T[] | null | undefined): T[] {
+  if (v == null) return []
+  return Array.isArray(v) ? v : [v]
+}
+
+function toNum(v: string | null | undefined): number | null {
+  if (v == null || v === '') return null
+  const n = Number(v)
+  return Number.isFinite(n) ? n : null
+}
+
+function splitList(v: string | null | undefined): string[] | null {
+  if (v == null || v === '') return null
+  return v
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+export type N4DataTableResponse = {
+  'query-response'?: {
+    'data-table'?: {
+      '@count'?: string
+      columns?: { column?: string | string[] }
+      rows?: { row?: N4RawRow | N4RawRow[] } | null
+    }
+  }
+}
+
+type N4RawRow = {
+  '@primary-key'?: string
+  field?: (string | null) | (string | null)[]
+}
+
+/**
+ * Parse the N4 `/unit` `query-response.data-table` JSON envelope into typed
+ * rows. Maps `field[]` onto `columns.column[]` by index, reads `@primary-key`
+ * as the Ufv_Gkey, and tolerates single-vs-array collapsing from XML→JSON.
+ */
+export function parseUnitDataTable(body: N4DataTableResponse): N4UnitRow[] {
+  const table = body?.['query-response']?.['data-table']
+  if (!table) return []
+
+  const columns = asArray(table.columns?.column).map((c) => String(c))
+  const rows = asArray(table.rows?.row ?? undefined)
+
+  const idx = (header: string): number => columns.indexOf(header)
+  const out: N4UnitRow[] = []
+
+  for (const row of rows) {
+    const fields = asArray(row.field)
+    const get = (header: string): string | null => {
+      const i = idx(header)
+      if (i < 0 || i >= fields.length) return null
+      const v = fields[i]
+      return v == null || v === '' ? null : String(v)
+    }
+
+    const raw: Record<string, string | null> = {}
+    columns.forEach((col, i) => {
+      raw[col] = fields[i] == null || fields[i] === '' ? null : String(fields[i])
+    })
+
+    const ufvGkey = row['@primary-key'] ? String(row['@primary-key']) : ''
+    const unitNbr = get('Unit Nbr') ?? ''
+    if (!ufvGkey || !unitNbr) continue
+
+    out.push({
+      ufvGkey,
+      unitNbr,
+      tState: get('T-State'),
+      vState: get('V-State'),
+      category: get('Category'),
+      lineOp: get('Line Op'),
+      typeIso: get('Type ISO'),
+      frghtKind: get('Frght Kind'),
+      ibActualVisit: get('I/B Actual Visit'),
+      obActualVisit: get('O/B Actual Visit'),
+      timeIn: get('Time In'),
+      timeOut: get('Time Out'),
+      impediments: splitList(get('Unit Impediments')),
+      cenNumber: get('CEN Number'),
+      vgmWeight: toNum(get('VGM Weight')),
+      cargoWtKg: toNum(get('Cargo Wt (kg)')),
+      tareWt: toNum(get('Tare Wt')),
+      weightKg: toNum(get('Weight (kg)')),
+      seals: [get('Seal Nbr1'), get('Seal Nbr2'), get('Seal Nbr3'), get('Seal Nbr4')].filter(
+        (s): s is string => !!s,
+      ),
+      dskNumber: get('DSK Number'),
+      loaded: get('Loaded'),
+      stops: parseTerminalStops(raw),
+      raw,
+    })
+  }
+
+  return out
+}

package/src/modules/terminal_tracking/lib/adapters/n4/parsers/vessel-data-table.ts

@@ -0,0 +1,60 @@
+import type { N4DataTableResponse } from './data-table'
+import type { N4VesselRow } from '../types'
+
+/** Coerce a value that may be a single item or an array into an array. */
+function asArray<T>(v: T | T[] | null | undefined): T[] {
+  if (v == null) return []
+  return Array.isArray(v) ? v : [v]
+}
+
+/**
+ * Parse the N4 `/VESSEL` `query-response.data-table` envelope into a single
+ * vessel-visit row. A `/VESSEL?VISIT_REF=` query targets exactly one visit, so
+ * we return the first row (or null when there are none). Columns are mapped by
+ * header name, mirroring parseUnitDataTable.
+ *
+ * Real columns: Visit, Vessel Name, I/B Vyg, O/B Vyg, Line, Phase, ETA, ETD,
+ * ATA, ATD, Begin Receive, DryCutoff. The `Visit` column equals the unit's
+ * `visitRefIn`/`visitRefOut` (the join key).
+ */
+export function parseVesselDataTable(body: N4DataTableResponse): N4VesselRow | null {
+  const table = body?.['query-response']?.['data-table']
+  if (!table) return null
+
+  const columns = asArray(table.columns?.column).map((c) => String(c))
+  const rows = asArray(table.rows?.row ?? undefined)
+  if (rows.length === 0) return null
+
+  const row = rows[0]
+  const fields = asArray(row.field)
+  const get = (header: string): string | null => {
+    const i = columns.indexOf(header)
+    if (i < 0 || i >= fields.length) return null
+    const v = fields[i]
+    return v == null || v === '' ? null : String(v)
+  }
+
+  const raw: Record<string, string | null> = {}
+  columns.forEach((col, i) => {
+    raw[col] = fields[i] == null || fields[i] === '' ? null : String(fields[i])
+  })
+
+  const visitRef = get('Visit')
+  if (!visitRef) return null
+
+  return {
+    visitRef,
+    vesselName: get('Vessel Name'),
+    ibVoyage: get('I/B Vyg'),
+    obVoyage: get('O/B Vyg'),
+    line: get('Line'),
+    phase: get('Phase'),
+    eta: get('ETA'),
+    etd: get('ETD'),
+    ata: get('ATA'),
+    atd: get('ATD'),
+    beginReceive: get('Begin Receive'),
+    dryCutoff: get('DryCutoff'),
+    raw,
+  }
+}

package/src/modules/terminal_tracking/lib/adapters/n4/proxy.ts

@@ -0,0 +1,24 @@
+import { ProxyAgent, type Dispatcher } from 'undici'
+
+/**
+ * Build (and memoise) an undici `ProxyAgent` for a terminal's `proxyUrl`, to be
+ * passed as the `dispatcher` on the N4 `fetch` calls so they egress through a
+ * whitelisted IP. Returns undefined when no proxy is configured (direct).
+ *
+ * Note: undici proxying is HTTP(S) CONNECT only — `proxyUrl` must be an
+ * http(s) forward proxy (e.g. tinyproxy/squid), not a SOCKS proxy.
+ */
+const cache = new Map<string, ProxyAgent>()
+
+export function proxyDispatcher(proxyUrl?: string | null): Dispatcher | undefined {
+  if (!proxyUrl) return undefined
+  let agent = cache.get(proxyUrl)
+  if (!agent) {
+    agent = new ProxyAgent(proxyUrl)
+    cache.set(proxyUrl, agent)
+  }
+  return agent
+}
+
+/** Init type for global fetch including undici's `dispatcher` (not in DOM types). */
+export type FetchInitWithDispatcher = RequestInit & { dispatcher?: Dispatcher }

package/src/modules/terminal_tracking/lib/adapters/n4/types.ts

@@ -0,0 +1,56 @@
+import type { TerminalStops } from '../../stops'
+
+/**
+ * Normalized representation of one N4 "Unit Facility Visit" row returned by
+ * the terminal `/unit` endpoint (the `query-response.data-table` envelope).
+ * Field names mirror the N4 column headers (mapped by name, not position).
+ */
+export type N4UnitRow = {
+  ufvGkey: string
+  unitNbr: string
+  tState?: string | null
+  vState?: string | null
+  category?: string | null
+  lineOp?: string | null
+  typeIso?: string | null
+  frghtKind?: string | null
+  ibActualVisit?: string | null
+  obActualVisit?: string | null
+  timeIn?: string | null
+  timeOut?: string | null
+  impediments?: string[] | null
+  cenNumber?: string | null
+  vgmWeight?: number | null
+  cargoWtKg?: number | null
+  tareWt?: number | null
+  weightKg?: number | null
+  seals?: string[] | null
+  dskNumber?: string | null
+  loaded?: string | null
+  /** Per-mode load/pickup STOP flags (Stop-Vsl / Stop-Road / Stop-Rail). */
+  stops: TerminalStops
+  /** The full header->value map for rawData persistence. */
+  raw: Record<string, string | null>
+}
+
+/**
+ * Normalized representation of one N4 vessel visit row returned by the `/VESSEL`
+ * endpoint. Date fields are raw strings ("yyyy-mm-dd hh:mm"); the adapter parses
+ * them via parseN4DateTime. There are two voyages — inbound and outbound.
+ */
+export type N4VesselRow = {
+  visitRef: string
+  vesselName: string | null
+  ibVoyage: string | null
+  obVoyage: string | null
+  line: string | null
+  phase: string | null
+  eta: string | null
+  etd: string | null
+  ata: string | null
+  atd: string | null
+  beginReceive: string | null
+  dryCutoff: string | null
+  /** The full header->value map for rawData persistence. */
+  raw: Record<string, string | null>
+}

package/src/modules/terminal_tracking/lib/adapters/zoned-time.ts

@@ -0,0 +1,65 @@
+/**
+ * Terminal timestamp timezone handling.
+ *
+ * Every terminal we integrate (BCT Gdańsk via N4, GCT and BCT Gdynia) reports
+ * event times as a naive wall-clock string — `2026-08-21 11:57`, with no offset.
+ * Those are *terminal-local* times, not UTC. Reading them as UTC (the old
+ * behaviour: append `Z`) shifted every displayed time by the zone's offset — in
+ * summer Europe/Warsaw is CEST (+02:00), so a gate-out of 11:57 rendered as
+ * 13:57 in the (Warsaw) UI.
+ *
+ * All current terminals sit in `Europe/Warsaw`; that is the default. When a
+ * terminal outside Poland is onboarded, pass its IANA zone into the parsers
+ * instead of relying on this constant.
+ */
+export const DEFAULT_TERMINAL_TIMEZONE = 'Europe/Warsaw'
+
+/**
+ * How far ahead of UTC `timeZone` is at the instant `utcMs`, in milliseconds.
+ * Uses `Intl` so DST is honoured (CET/CEST for Europe/Warsaw) without any
+ * external timezone library.
+ */
+function zoneOffsetMs(utcMs: number, timeZone: string): number {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    hour12: false,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  }).formatToParts(new Date(utcMs))
+  const f: Record<string, number> = {}
+  for (const p of parts) if (p.type !== 'literal') f[p.type] = Number(p.value)
+  // Some engines render midnight as hour 24 rather than 0.
+  const hour = f.hour === 24 ? 0 : f.hour
+  const asIfUtc = Date.UTC(f.year, f.month - 1, f.day, hour, f.minute, f.second)
+  return asIfUtc - utcMs
+}
+
+/**
+ * Convert a naive wall-clock datetime — its components written in `timeZone`
+ * with no offset — to the correct UTC instant.
+ *
+ * e.g. `(2026, 8, 21, 11, 57, 0, 'Europe/Warsaw')` during CEST (+02:00) yields
+ * `2026-08-21T09:57:00.000Z`.
+ *
+ * `month` is 1-based (January = 1). Within a DST transition (the ~1h gap or
+ * overlap twice a year) the result may be off by the DST delta — acceptable for
+ * terminal event timestamps, which never land inside that window in practice.
+ */
+export function zonedNaiveToUtc(
+  year: number,
+  month: number,
+  day: number,
+  hour: number,
+  minute: number,
+  second: number,
+  timeZone: string,
+): Date {
+  // First approximation: pretend the wall-clock components are already UTC,
+  // then subtract the zone's offset at (approximately) that instant.
+  const asUtc = Date.UTC(year, month - 1, day, hour, minute, second)
+  return new Date(asUtc - zoneOffsetMs(asUtc, timeZone))
+}