edfcore 0.1.5 → 0.1.7

package/src/envelope.ts

@@ -0,0 +1,352 @@
+/**
+ * Min/max envelope decimation.
+ *
+ * Layer 7. A twelve-hour recording at 256 Hz is eleven million samples per channel, and a plot is
+ * a thousand pixels wide. Something has to reduce eleven million numbers to a thousand, and which
+ * reduction you pick decides whether the picture is true.
+ *
+ * Taking every 11,000th sample is the obvious choice and the wrong one: a spike, a spindle or an
+ * artifact is a handful of samples wide, so subsampling hits it with probability near zero and
+ * the trace looks calm exactly where a reader most needs it not to. Keeping the MINIMUM and
+ * MAXIMUM of each bucket keeps every extreme, at two numbers per pixel. That is the reduction a
+ * waveform viewer wants, and it is why this exists as its own function rather than as an option
+ * on `readWindow`: the return type is different, so an option would have to change it.
+ *
+ * This is decimation for display, not analysis. There is no filtering and no anti-aliasing —
+ * an envelope is a faithful summary of the samples that are there, not a resampled signal, and
+ * resampling remains a permanent non-goal.
+ *
+ * Memory is bounded by the record chunk, never by the window: a run of a million records is
+ * folded into the buckets a chunk at a time, so an envelope over a whole recording costs the
+ * buckets plus one chunk.
+ */
+
+import { decodeDigitalCounted } from './decode/digital.js';
+import { EdfScalingError } from './errors.js';
+import { readRecordBytes } from './io/read.js';
+import { scanChunkRecords } from './record-index.js';
+import { decodeAnnotations } from './tal/annotations.js';
+import { ticksToSeconds } from './tal/ticks.js';
+import { resolveTimeWindow } from './time/window.js';
+import type {
+  EdfChunkSignal,
+  EdfDiagnostic,
+  EdfEnvelopeChunk,
+  EdfEnvelopeSignal,
+  EdfHeader,
+  EdfPhysicalEnvelope,
+  EdfRecording,
+  EdfSignal,
+  EnvelopeSelection,
+  ReadOptions,
+  RecordRange,
+} from './types.js';
+
+/** Per-signal accumulator, reused across every chunk of one contiguous run. */
+interface Accumulator {
+  readonly signal: EdfSignal;
+  readonly min: Int32Array;
+  readonly max: Int32Array;
+  readonly counts: Int32Array;
+  /** Samples of this signal already folded in, i.e. its position on the run's sample grid. */
+  consumed: number;
+  outOfRange: number;
+  scratch: Int32Array | undefined;
+}
+
+function assertPositiveInteger(value: number, name: string): void {
+  if (Number.isSafeInteger(value) && value > 0) return;
+  throw new RangeError(
+    `readEnvelope(): ${name} must be a positive whole number, received ${value}. ` +
+      'Next: pass the pixel width of the plot you are drawing into.',
+  );
+}
+
+/**
+ * Reduces a time window to per-bucket minima and maxima, one chunk per contiguous run.
+ *
+ * The shape mirrors `readWindow` exactly — an array of chunks, one per run, empty when the window
+ * selects nothing — so a caller that already handles gaps handles envelopes for free.
+ */
+export async function readEnvelope(
+  recording: EdfRecording,
+  selection: EnvelopeSelection,
+  options?: ReadOptions,
+): Promise<readonly EdfEnvelopeChunk[]> {
+  assertPositiveInteger(selection.buckets, 'buckets');
+  // Validated before the window is resolved, for the same reason readWindow does it: a bad
+  // signalIndices must not read back as an empty stretch of recording.
+  resolveEnvelopeSignals(recording.header, selection.signalIndices);
+
+  const ranges = resolveTimeWindow(
+    recording.timeline,
+    recording.index,
+    selection.startSeconds,
+    selection.durationSeconds,
+  );
+
+  const chunks: EdfEnvelopeChunk[] = [];
+  for (const records of ranges) {
+    chunks.push(await reduceRange(recording, records, selection, options));
+  }
+  return Object.freeze(chunks);
+}
+
+function resolveEnvelopeSignals(
+  header: EdfHeader,
+  signalIndices: readonly number[],
+): readonly EdfSignal[] {
+  const seen = new Set<number>();
+  const signals: EdfSignal[] = [];
+  for (const signalIndex of signalIndices) {
+    if (seen.has(signalIndex)) continue;
+    seen.add(signalIndex);
+    const signal = header.signals[signalIndex];
+    if (signal === undefined) {
+      throw new RangeError(
+        `readEnvelope(): signalIndex ${signalIndex} is outside the ${header.signals.length} ` +
+          'signals this file declares. Next: pass an index from header.dataSignalIndices.',
+      );
+    }
+    if (signal.kind === 'annotations') {
+      throw new RangeError(
+        `readEnvelope(): signal ${signalIndex} (${JSON.stringify(signal.label)}) is this file's ` +
+          'annotations channel; its bytes are TAL text, not samples, so an envelope over them ' +
+          'would be an envelope over ASCII. Next: call readAnnotations() instead.',
+      );
+    }
+    signals.push(signal);
+  }
+  return signals;
+}
+
+async function reduceRange(
+  recording: EdfRecording,
+  records: RecordRange,
+  selection: EnvelopeSelection,
+  options?: ReadOptions,
+): Promise<EdfEnvelopeChunk> {
+  const { source, header, timeline } = recording;
+  const signals = resolveEnvelopeSignals(header, selection.signalIndices);
+  const diagnostics: EdfDiagnostic[] = [];
+
+  // More buckets than the densest signal has samples in this run would leave holes that mean
+  // nothing, so the request is clamped rather than honoured literally.
+  const densestSamples = signals.reduce(
+    (most, signal) => Math.max(most, signal.samplesPerRecord * records.count),
+    0,
+  );
+  const bucketCount = Math.max(1, Math.min(selection.buckets, densestSamples));
+
+  const accumulators: Accumulator[] = signals.map((signal) => ({
+    signal,
+    // Int32Array zero-fills, so the sentinels have to be written explicitly: a bucket nothing
+    // landed in must be distinguishable from a bucket whose samples were all zero.
+    min: new Int32Array(bucketCount).fill(0),
+    max: new Int32Array(bucketCount).fill(0),
+    counts: new Int32Array(bucketCount),
+    consumed: 0,
+    outOfRange: 0,
+    scratch: undefined,
+  }));
+
+  const chunkRecords = scanChunkRecords(header, options?.maxMaterializeBytes);
+  let byteLength = 0;
+  let firstOnsetTicks: bigint | undefined;
+  let lastOnsetTicks: bigint | undefined;
+  let scanned = 0;
+
+  while (scanned < records.count) {
+    const slice: RecordRange = {
+      start: records.start + scanned,
+      count: Math.min(chunkRecords, records.count - scanned),
+    };
+    const bytes = await readRecordBytes(source, header, slice, options);
+    byteLength += bytes.length;
+
+    // Never strict: a defect in one record must not cost the caller the whole picture.
+    const annotations = decodeAnnotations(header, bytes, slice, {
+      originTicks: timeline.startOffsetTicks,
+    });
+    for (const diagnostic of annotations.diagnostics) diagnostics.push(diagnostic);
+    const onsets = annotations.recordOnsetTicks;
+    if (firstOnsetTicks === undefined) firstOnsetTicks = onsets[0];
+    const lastInSlice = onsets[slice.count - 1];
+    if (lastInSlice !== undefined) lastOnsetTicks = lastInSlice;
+
+    for (const accumulator of accumulators) {
+      foldChunk(accumulator, header, bytes, slice, records, bucketCount, options);
+    }
+
+    scanned += slice.count;
+  }
+
+  const durationTicks = header.recordDurationTicks;
+  const startTicks = (firstOnsetTicks ?? timeline.startOffsetTicks) - timeline.startOffsetTicks;
+  const spanTicks =
+    firstOnsetTicks !== undefined && lastOnsetTicks !== undefined
+      ? lastOnsetTicks + durationTicks - firstOnsetTicks
+      : durationTicks * BigInt(records.count);
+  const startSeconds = ticksToSeconds(startTicks);
+  const durationSeconds = ticksToSeconds(spanTicks);
+
+  const envelopeSignals: EdfEnvelopeSignal[] = accumulators.map((accumulator) => ({
+    signalIndex: accumulator.signal.index,
+    min: accumulator.min,
+    max: accumulator.max,
+    counts: accumulator.counts,
+    sampleCount: accumulator.consumed,
+    firstSampleIndex: records.start * accumulator.signal.samplesPerRecord,
+    startSeconds,
+    outOfDigitalRangeCount: accumulator.outOfRange,
+  }));
+
+  return Object.freeze({
+    records,
+    startSeconds,
+    durationSeconds,
+    bucketCount,
+    secondsPerBucket: bucketCount > 0 ? durationSeconds / bucketCount : 0,
+    byteLength,
+    signals: Object.freeze(envelopeSignals),
+    precededByGap: undefined,
+    diagnostics: Object.freeze(diagnostics),
+  });
+}
+
+/**
+ * Folds one chunk of one signal into the buckets.
+ *
+ * The bucket of a sample is decided by its position on the WHOLE run's grid, not the chunk's, so
+ * the chunk size cannot move a sample from one bucket to another. That is the same rule the
+ * record scan learned the hard way: chunking bounds memory and must never change the answer.
+ */
+function foldChunk(
+  accumulator: Accumulator,
+  header: EdfHeader,
+  bytes: Uint8Array,
+  slice: RecordRange,
+  run: RecordRange,
+  bucketCount: number,
+  options?: ReadOptions,
+): void {
+  const totalSamples = accumulator.signal.samplesPerRecord * run.count;
+  if (totalSamples === 0) return;
+
+  const decoded = decodeDigitalCounted(
+    header,
+    bytes,
+    slice,
+    accumulator.signal.index,
+    accumulator.scratch,
+    options,
+  );
+  // decodeDigitalCounted reuses the buffer when it is large enough, so the allocation happens
+  // once per signal per run rather than once per chunk.
+  accumulator.scratch = decoded.digital;
+  accumulator.outOfRange += decoded.outOfDigitalRangeCount;
+
+  const samples = decoded.digital;
+  // The buffer is reused across chunks, so it can be LONGER than this slice. The slice's own
+  // sample count is what must be folded, or the tail of a previous, larger chunk is counted again.
+  const sampleCount = accumulator.signal.samplesPerRecord * slice.count;
+  const { min, max, counts } = accumulator;
+  let position = accumulator.consumed;
+
+  for (let i = 0; i < sampleCount; i += 1) {
+    const value = samples[i] as number;
+    // Integer arithmetic on the run grid: floor(position * buckets / totalSamples).
+    const bucket = Math.min(bucketCount - 1, Math.floor((position * bucketCount) / totalSamples));
+    const seen = counts[bucket] as number;
+    if (seen === 0) {
+      min[bucket] = value;
+      max[bucket] = value;
+    } else {
+      if (value < (min[bucket] as number)) min[bucket] = value;
+      if (value > (max[bucket] as number)) max[bucket] = value;
+    }
+    counts[bucket] = seen + 1;
+    position += 1;
+  }
+
+  accumulator.consumed = position;
+}
+
+/**
+ * Converts a digital envelope to physical units.
+ *
+ * Not `toPhysical` applied twice, and the reason is the sign of the gain. The affine transform
+ * `bitValue * (offset + digital)` is DECREASING when `bitValue` is negative — a spec-sanctioned
+ * arrangement that edfcore reports rather than rejects — and a decreasing map sends the smallest
+ * digital value to the largest physical one. Mapping `min` to `min` would then produce an
+ * envelope whose lower bound is above its upper bound, and a viewer would draw it inside out.
+ */
+export function toPhysicalEnvelope(
+  signal: EdfSignal,
+  envelope: EdfEnvelopeSignal,
+): EdfPhysicalEnvelope {
+  const scale = signal.scale;
+  if (scale === undefined) {
+    throw new EdfScalingError(
+      `signal ${signal.index} (${JSON.stringify(signal.label)}) has no usable scale, so its ` +
+        'envelope has no physical units. Next: check signal.scale before converting, or plot ' +
+        'the digital envelope as it is.',
+      { code: 'SCALE_UNAVAILABLE', signalIndex: signal.index, label: signal.label },
+    );
+  }
+
+  const length = envelope.min.length;
+  const low = new Float64Array(length);
+  const high = new Float64Array(length);
+  const decreasing = scale.bitValue < 0;
+
+  for (let i = 0; i < length; i += 1) {
+    const a = scale.bitValue * (scale.offset + (envelope.min[i] as number));
+    const b = scale.bitValue * (scale.offset + (envelope.max[i] as number));
+    low[i] = decreasing ? b : a;
+    high[i] = decreasing ? a : b;
+  }
+  return { min: low, max: high };
+}
+
+/**
+ * The envelope of an already-decoded chunk signal, without another read.
+ *
+ * For a caller who has samples in hand and wants them plotted: same reduction, same bucket rule,
+ * no I/O.
+ */
+export function envelopeOfSamples(chunkSignal: EdfChunkSignal, buckets: number): EdfEnvelopeSignal {
+  assertPositiveInteger(buckets, 'buckets');
+  const samples = chunkSignal.digital;
+  const total = samples.length;
+  const bucketCount = Math.max(1, Math.min(buckets, total));
+
+  const min = new Int32Array(bucketCount);
+  const max = new Int32Array(bucketCount);
+  const counts = new Int32Array(bucketCount);
+
+  for (let i = 0; i < total; i += 1) {
+    const value = samples[i] as number;
+    const bucket = Math.min(bucketCount - 1, Math.floor((i * bucketCount) / total));
+    const seen = counts[bucket] as number;
+    if (seen === 0) {
+      min[bucket] = value;
+      max[bucket] = value;
+    } else {
+      if (value < (min[bucket] as number)) min[bucket] = value;
+      if (value > (max[bucket] as number)) max[bucket] = value;
+    }
+    counts[bucket] = seen + 1;
+  }
+
+  return {
+    signalIndex: chunkSignal.signalIndex,
+    min,
+    max,
+    counts,
+    sampleCount: total,
+    firstSampleIndex: chunkSignal.firstSampleIndex,
+    startSeconds: chunkSignal.startSeconds,
+    outOfDigitalRangeCount: chunkSignal.outOfDigitalRangeCount,
+  };
+}

package/src/header/parse.ts

@@ -47,6 +47,9 @@ import { parsePatientId, parseRecordingId } from './identification.js';
 import { buildSignals, parseSignalHeaders, signalFieldOffset } from './signals.js';
 import { detectVariant } from './variant.js';
 
+/** The largest value a `BigInt64Array` element holds: about 29,000 years of 100 ns ticks. */
+const MAX_REPRESENTABLE_TICKS: bigint = 2n ** 63n - 1n;
+
 interface RecordCountResolution {
   readonly recordCount: number;
   readonly recordCountSource: EdfHeader['recordCountSource'];
@@ -333,6 +336,39 @@ export function parseHeader(
     sink,
   );
 
+  // ---- 9b. A declared span no tick count can hold. ----------------------------------------
+  //
+  // Every onset array in edfcore is a BigInt64Array, and assignment to one wraps modulo 2^64
+  // rather than throwing. Saturating keeps such an array non-decreasing, but it cannot make it
+  // meaningful: clamping collapses the spacing between records, so a file declaring a span past
+  // the tick range indexes as one segment per record either way. There is no honest onset to
+  // report, which is what makes this fatal rather than a warning.
+  //
+  // Unreachable for a real recording — the bound is over 29,000 years — but `recordDuration` is
+  // free-form ASCII and `parseEdfNumber` accepts exponent notation, so `1E30` in an 8-byte field
+  // is enough to ask for it.
+  const declaredSpanTicks = recordDurationTicks * BigInt(recordCount);
+  if (declaredSpanTicks > MAX_REPRESENTABLE_TICKS) {
+    throw fatalError({
+      code: 'RECORDING_SPAN_UNREPRESENTABLE',
+      message:
+        `the header declares ${recordCount} records of ${recordDurationSeconds} s, a total span ` +
+        `of ${declaredSpanTicks} ticks of 100 ns. edfcore stores every record onset as a signed ` +
+        `64-bit tick count, whose largest value is ${MAX_REPRESENTABLE_TICKS} — about 29,000 ` +
+        'years — so the later onsets in this file have no representable value and every time it ' +
+        'reported would be invented. EDF specification, header (duration of a data record). ' +
+        `Next: the record duration lives at offset ${HEADER_FIELDS.recordDuration.offset} and ` +
+        `is written as ${JSON.stringify(raw.recordDuration)}; header.raw keeps it as written.`,
+      field: 'recordDuration',
+      byteOffset: HEADER_FIELDS.recordDuration.offset,
+      byteLength: HEADER_FIELDS.recordDuration.length,
+      raw: raw.recordDuration,
+      expected: `a span of at most ${MAX_REPRESENTABLE_TICKS} ticks`,
+      actual: `${declaredSpanTicks} ticks`,
+      specReference: 'EDF specification, header (duration of a data record)',
+    });
+  }
+
   // ---- 10. EDF+ without an annotations signal has no per-record timing to report. ---------
   if (variant.isPlus && parsed.annotationSignalIndices.length === 0) {
     throw fatalError({

package/src/index.ts

@@ -43,12 +43,15 @@ export type {
   EdfClockTime,
   EdfDiagnostic,
   EdfDiagnosticCode,
+  EdfEnvelopeChunk,
+  EdfEnvelopeSignal,
   EdfGap,
   EdfHeader,
   EdfInspection,
   EdfKnownDiagnosticCode,
   EdfLocation,
   EdfPatientId,
+  EdfPhysicalEnvelope,
   EdfRawHeaderFields,
   EdfRawSignalFields,
   EdfRecordIndex,
@@ -61,6 +64,7 @@ export type {
   EdfStartTime,
   EdfTimeline,
   EdfVariant,
+  EnvelopeSelection,
   FetchLike,
   HttpResponseLike,
   HttpSourceOptions,
@@ -147,5 +151,6 @@ export { buildRecordIndex, buildTimeline } from './record-index.js';
 // Convenience layer
 // ===========================================================================
 
+export { envelopeOfSamples, readEnvelope, toPhysicalEnvelope } from './envelope.js';
 export { inspectEdf } from './inspect.js';
 export { openEdf, readAnnotations, readRecords, readWindow } from './recording.js';

package/src/record-index.ts

@@ -27,10 +27,11 @@
  */
 
 import { DEFAULT_MAX_MATERIALIZE_BYTES } from './constants.js';
+import { appendDiagnostics } from './diagnostics/collector.js';
 import { EdfRangeError } from './errors.js';
 import { readRecordBytes } from './io/read.js';
 import { decodeAnnotations } from './tal/annotations.js';
-import { secondsToTicks, ticksToSeconds } from './tal/ticks.js';
+import { saturateToInt64, secondsToTicks, ticksToSeconds } from './tal/ticks.js';
 import { buildSegmentation } from './time/segments.js';
 import {
   assertMonotonicOnsetArray,
@@ -81,7 +82,13 @@ export function scanChunkRecords(header: EdfHeader, maxMaterializeBytes?: number
  * definition for a plain EDF or BDF file, where record onsets are not stored at all.
  */
 function nominalOnsetTicks(header: EdfHeader, recordIndex: number): bigint {
-  return BigInt(recordIndex) * header.recordDurationTicks;
+  // Saturated, because every onset array here is a BigInt64Array and assignment to one wraps
+  // rather than throwing. A file with no annotation channel gets its onsets purely from this
+  // arithmetic, so an overflowing recordDuration produced an array that jumped backwards — read
+  // downstream as one segment per record with negative gaps, reported as a 'complete' index with
+  // no diagnostic at all. decodeAnnotations already saturated its own derived onsets; this path
+  // was the one that did not.
+  return saturateToInt64(BigInt(recordIndex) * header.recordDurationTicks);
 }
 
 /** True when the file stores per-record onsets, i.e. when probing can learn anything. */
@@ -280,7 +287,7 @@ export async function buildTimeline(
     // fake a discontinuity in a conforming file and make readWindow refuse every window in it.
     const probe = await probeOnset(source, header, recordIndex, probeOptions(options, memo.get(0)));
     memo.set(recordIndex, probe.ticks);
-    probeDiagnostics.push(...probe.diagnostics);
+    appendDiagnostics(probeDiagnostics, probe.diagnostics);
     probes.push({ recordIndex, onsetTicks: probe.ticks });
   }
 

package/src/tal/annotations.ts

@@ -54,7 +54,7 @@ import {
   type TalIssueCode,
   type TalTextEncoding,
 } from './grammar.js';
-import { ticksToSeconds } from './ticks.js';
+import { saturateToInt64, ticksToSeconds } from './ticks.js';
 
 const ANNOTATIONS_SPEC = "EDF+ specification 2.2 (the 'EDF Annotations' signal)";
 const TIMEKEEPING_SPEC = 'EDF+ specification 2.2.1 (time keeping of data records)';
@@ -133,20 +133,6 @@ interface ObservedOnset {
   readonly raw: string;
 }
 
-/**
- * A `BigInt64Array` wraps silently on assignment, so a derived onset is saturated rather than
- * wrapped. Reaching either bound needs a declared geometry that is already impossible (~29,000
- * years of records); saturating keeps the array non-decreasing where wrapping would invert it.
- */
-const INT64_MIN: bigint = -(2n ** 63n);
-const INT64_MAX: bigint = 2n ** 63n - 1n;
-
-function saturateToInt64(ticks: bigint): bigint {
-  if (ticks > INT64_MAX) return INT64_MAX;
-  if (ticks < INT64_MIN) return INT64_MIN;
-  return ticks;
-}
-
 function describeRange(range: RecordRange): string {
   return `{ start: ${range.start}, count: ${range.count} }`;
 }

package/src/tal/ticks.ts

@@ -150,6 +150,29 @@ export function ticksToSeconds(ticks: bigint): number {
   return Number(wholeSeconds) + Number(remainder) / TICKS_PER_SECOND_FLOAT;
 }
 
+const INT64_MIN: bigint = -(2n ** 63n);
+const INT64_MAX: bigint = 2n ** 63n - 1n;
+
+/**
+ * Clamps a tick count to what a `BigInt64Array` element can hold.
+ *
+ * Assignment to a `BigInt64Array` wraps modulo 2^64 rather than throwing, and every onset array
+ * in edfcore is one. Wrapping turns a monotonically increasing series into one that jumps
+ * backwards, which downstream code reads as a genuine discontinuity: a file whose declared
+ * record duration overflows the range then indexes as one segment per record, with negative
+ * gaps between them and no diagnostic anywhere.
+ *
+ * Saturating keeps the array non-decreasing, so an absurd geometry stays visibly absurd instead
+ * of becoming plausibly wrong. Reaching either bound needs a declared geometry that is already
+ * impossible — over 29,000 years of records — but `recordDuration` is a free-form ASCII field
+ * that accepts exponent notation, so three bytes are enough to ask for it.
+ */
+export function saturateToInt64(ticks: bigint): bigint {
+  if (ticks > INT64_MAX) return INT64_MAX;
+  if (ticks < INT64_MIN) return INT64_MIN;
+  return ticks;
+}
+
 /**
  * Seconds to ticks, rounded to the NEAREST tick (ties away from zero is not required; ties go
  * toward +Infinity, as `Math.round` does).

package/src/types.ts

@@ -367,6 +367,59 @@ export interface EdfChunk {
   readonly diagnostics: readonly EdfDiagnostic[];
 }
 
+/**
+ * One signal's min/max envelope over a window, at a resolution the caller chose.
+ *
+ * The unit is the bucket, not the sample: `min[i]` and `max[i]` are the extremes of every sample
+ * that fell in bucket `i`. Drawing a twelve-hour recording into a thousand pixels needs exactly
+ * this and nothing else — the peaks are what a reader of an EEG trace is looking at, and they
+ * are the first thing naive subsampling throws away.
+ */
+export interface EdfEnvelopeSignal {
+  readonly signalIndex: number;
+  /** Digital extremes per bucket. Convert with `toPhysicalEnvelope`, never with `toPhysical`. */
+  readonly min: Int32Array;
+  readonly max: Int32Array;
+  /** Samples that landed in each bucket. Zero where the window had no samples to cover it. */
+  readonly counts: Int32Array;
+  /** Total samples reduced, i.e. the sum of `counts`. */
+  readonly sampleCount: number;
+  readonly firstSampleIndex: number;
+  readonly startSeconds: number;
+  readonly outOfDigitalRangeCount: number;
+}
+
+/** A contiguous run of records, reduced to buckets. One per run, exactly as `readWindow` splits. */
+export interface EdfEnvelopeChunk {
+  readonly records: RecordRange;
+  readonly startSeconds: number;
+  readonly durationSeconds: number;
+  /** Buckets actually filled. Never more than requested, and fewer for a short run. */
+  readonly bucketCount: number;
+  readonly secondsPerBucket: number;
+  readonly byteLength: number;
+  readonly signals: readonly EdfEnvelopeSignal[];
+  readonly precededByGap: EdfGap | undefined;
+  readonly diagnostics: readonly EdfDiagnostic[];
+}
+
+export interface EnvelopeSelection extends WindowSelection {
+  /**
+   * How many buckets to reduce the window into — in a viewer, the pixel width of the plot.
+   *
+   * A bucket per pixel is the point: asking for more buckets than the window has samples wastes
+   * work and yields empty buckets, so the count is clamped to the sample count of the densest
+   * signal in the run.
+   */
+  readonly buckets: number;
+}
+
+/** A physical-unit envelope. Separate from the digital one for the same reason `toPhysical` is. */
+export interface EdfPhysicalEnvelope {
+  readonly min: Float64Array;
+  readonly max: Float64Array;
+}
+
 export interface EdfAnnotation {
   /** Verbatim on-disk value, relative to the header startdate/starttime (EDF+ 2.2.4). */
   readonly onsetSecondsFromHeaderStart: number;

package/src/validate.ts

@@ -21,7 +21,7 @@
 import { trimEdfField } from './bytes/latin1.js';
 import { DEFAULT_MAX_MATERIALIZE_BYTES, EDF_RECOMMENDED_MAX_RECORD_BYTES } from './constants.js';
 import { decodeDigitalCounted } from './decode/digital.js';
-import { createDiagnostic } from './diagnostics/collector.js';
+import { appendDiagnostics, createDiagnostic } from './diagnostics/collector.js';
 import { EdfBudgetError } from './errors.js';
 import { calendarDatesEqual, formatCalendarDate, isValidCalendarDate } from './header/dates.js';
 import { signalFieldOffset } from './header/signals.js';
@@ -534,7 +534,7 @@ async function traverse(
       originTicks: recording.timeline.startOffsetTicks,
     });
     onsets.set(decoded.recordOnsetTicks, records.start);
-    diagnostics.push(...decoded.diagnostics);
+    appendDiagnostics(diagnostics, decoded.diagnostics);
 
     for (const accumulator of accumulators) {
       const digital = decodeDigitalCounted(
@@ -604,7 +604,7 @@ export async function validateRecording(
   const mustReadOnsets = supplied === undefined && !onsetsAreArithmetic;
   const traversal =
     scanSamples || mustReadOnsets ? await traverse(recording, options, scanSamples) : undefined;
-  if (traversal !== undefined) diagnostics.push(...traversal.diagnostics);
+  if (traversal !== undefined) appendDiagnostics(diagnostics, traversal.diagnostics);
 
   let segmentCount: number;
   let gaps: readonly EdfGap[];