edfcore 0.1.2 → 0.1.4

package/src/record-index.ts

@@ -256,8 +256,11 @@ export async function buildTimeline(
 
   const probeOptions = (
     readOptions: ReadOptions | undefined,
-  ): DecodeAnnotationsOptions & ReadOptions =>
-    readOptions === undefined ? { strict } : { ...readOptions, strict };
+    originTicks?: bigint,
+  ): DecodeAnnotationsOptions & ReadOptions => {
+    const base = readOptions === undefined ? { strict } : { ...readOptions, strict };
+    return originTicks === undefined ? base : { ...base, originTicks };
+  };
 
   const memo = new Map<number, bigint>();
   const probes: RecordOnsetProbe[] = [];
@@ -271,7 +274,11 @@ export async function buildTimeline(
       probes.push({ recordIndex, onsetTicks: ticks });
       continue;
     }
-    const probe = await probeOnset(source, header, recordIndex, probeOptions(options));
+    // Record 0 is probed first and defines the origin, so by the time the last record is probed
+    // its true onset is in `memo`. Without handing it over, a last record with no timekeeping TAL
+    // derived its onset from zero and appeared to sit `startOffset` seconds early — enough to
+    // 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);
     probes.push({ recordIndex, onsetTicks: probe.ticks });
@@ -287,7 +294,12 @@ export async function buildTimeline(
       memo.set(recordIndex, ticks);
       return ticks;
     }
-    const probe = await probeOnset(source, header, recordIndex, probeOptions(readOptions));
+    const probe = await probeOnset(
+      source,
+      header,
+      recordIndex,
+      probeOptions(readOptions, timeline.startOffsetTicks),
+    );
     memo.set(recordIndex, probe.ticks);
     return probe.ticks;
   }
@@ -339,7 +351,14 @@ async function scanOnsets(
       count: Math.min(chunkRecords, recordCount - scanned),
     };
     const bytes = await readRecordBytes(source, header, records, options);
-    const decoded = decodeAnnotations(header, bytes, records, options);
+    // The origin comes from the recording, not from whatever this chunk happens to contain.
+    // Chunking is a memory-bounding detail and must not change the answer: without this, a chunk
+    // holding no observed onset derived from zero, so the onsets, the segments, the gaps and
+    // even a fatal TIMELINE_NOT_MONOTONIC varied with maxMaterializeBytes.
+    const decoded = decodeAnnotations(header, bytes, records, {
+      ...options,
+      originTicks: recording.timeline.startOffsetTicks,
+    });
     onsets.set(decoded.recordOnsetTicks, scanned);
     scanned += records.count;
     options?.onProgress?.(scanned, recordCount);

package/src/recording.ts

@@ -135,7 +135,14 @@ async function readChunk(
   // Never strict, and not because the flag was lost: a read that threw on an impolite TAL in a
   // record the caller asked for would return no samples at all over a defect in a different
   // channel. The defects land on `chunk.diagnostics`, next to the data they were found beside.
-  const annotations = decodeAnnotations(header, bytes, records);
+  // `originTicks` is the recording's own start, not this range's. It is already known here — the
+  // next few lines rebase against it — and without passing it down, a first record whose
+  // timekeeping TAL is missing derived its onset from zero. The same record then reported one
+  // start time when read alone and another when read beside a neighbour that did carry a TAL,
+  // and that start is the grid origin trimToWindow measures from.
+  const annotations = decodeAnnotations(header, bytes, records, {
+    originTicks: timeline.startOffsetTicks,
+  });
   const onsets = annotations.recordOnsetTicks;
   assertMonotonicOnsetArray(onsets, records.start);
 

package/src/tal/annotations.ts

@@ -445,9 +445,15 @@ export function decodeAnnotations(
 
   // Record 0's onset, observed when it was decoded and derived from the first record that was
   // otherwise. For a continuous file the derivation is exact; see the rebasing note below.
+  //
+  // With no observed onset anywhere in this range there is nothing local to derive from, and the
+  // origin has to come from the caller. Falling back to zero instead made the result depend on
+  // the range: the same record got one onset when read alone and another when read alongside a
+  // neighbour that did carry a timekeeping TAL, which in turn made chunk boundaries, segment
+  // boundaries and even a fatal TIMELINE_NOT_MONOTONIC a function of the scan chunk size.
   const baseTicks =
     firstObserved === undefined
-      ? 0n
+      ? (options?.originTicks ?? 0n)
       : firstObserved.ticks - BigInt(firstObserved.recordIndex) * durationTicks;
 
   const recordOnsetTicks = new BigInt64Array(records.count);

package/src/types.ts

@@ -449,6 +449,21 @@ export interface WindowSelection {
 export interface DecodeAnnotationsOptions extends ParseOptions {
   /** Defaults to every annotation signal. Only the first carries timekeeping. */
   readonly signalIndices?: readonly number[];
+  /**
+   * The recording's own time origin, for deriving the onset of a record whose timekeeping TAL
+   * is missing.
+   *
+   * A missing timekeeping TAL is a warning, not a fatal error, and such a record is documented
+   * to get `start + recordIndex * recordDuration`. That `start` can only be known by a caller
+   * who has already seen record 0. Without it the derivation falls back to an origin of zero,
+   * which is right only for a file whose first record starts at zero — and makes the answer
+   * depend on which records happened to share the call, because a range containing no observed
+   * onset at all gets a different origin from one that contains one.
+   *
+   * Pass `timeline.startOffsetTicks` whenever it is known. Decoding a range in isolation, as
+   * `openEdf` does before any timeline exists, correctly omits it.
+   */
+  readonly originTicks?: bigint;
 }
 
 /** Header-only triage. Reads at most 128 KiB and never throws on malformed content. */

package/src/validate.ts

@@ -19,9 +19,10 @@
  */
 
 import { trimEdfField } from './bytes/latin1.js';
-import { EDF_RECOMMENDED_MAX_RECORD_BYTES } from './constants.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 { EdfBudgetError } from './errors.js';
 import { calendarDatesEqual, formatCalendarDate, isValidCalendarDate } from './header/dates.js';
 import { signalFieldOffset } from './header/signals.js';
 import { readRecordBytes } from './io/read.js';
@@ -55,6 +56,9 @@ export type { ObservedSignalStats, ValidateOptions, ValidationReport } from './t
 const LABEL_SPEC = 'EDF+ additional specification 9 (standard texts and labels)';
 const TIMEKEEPING_SPEC = 'EDF+ specification 2.2.1 (time keeping of data records)';
 
+/** The sample-scan scratch buffer is an `Int32Array`, so four bytes per sample. */
+const BYTES_PER_SCRATCH_SAMPLE = 4;
+
 /**
  * The signal types EDF+ additional specification 9 names.
  *
@@ -479,8 +483,17 @@ async function traverse(
     : [];
 
   const chunkRecords = scanChunkRecords(header, options?.maxMaterializeBytes);
-  // One scratch array for every signal and every chunk. Bounded by chunkRecords *
-  // max(samplesPerRecord) * 4 bytes, which is at most twice the chunk's own byte size.
+  /*
+   * One scratch array for every signal and every chunk.
+   *
+   * This is normally bounded by the chunk's own byte size, because `scanChunkRecords` fits the
+   * chunk into a scan block. That bound fails for a single record larger than the whole block:
+   * the record count floors to 1 and the scratch size becomes `samplesPerRecord` unclamped, up
+   * to the 99,999,999 an 8-byte EDF field can hold — a 400 MB allocation reachable from one
+   * corrupted digit in a 512-byte file, made before any read, so no downstream check can catch
+   * it. Validation exists to be pointed at untrusted files, so it is exactly the caller who
+   * needs the budget honoured rather than a documented cap that only the read path respects.
+   */
   let scratch: Int32Array | undefined;
   if (scanSamples) {
     let maxSamplesPerRecord = 0;
@@ -490,6 +503,18 @@ async function traverse(
         maxSamplesPerRecord = Math.max(maxSamplesPerRecord, signal.samplesPerRecord);
       }
     }
+    const scratchBytes = chunkRecords * maxSamplesPerRecord * BYTES_PER_SCRATCH_SAMPLE;
+    const budgetBytes = options?.maxMaterializeBytes ?? DEFAULT_MAX_MATERIALIZE_BYTES;
+    if (scratchBytes > budgetBytes) {
+      throw new EdfBudgetError(
+        `Scanning samples needs a ${scratchBytes}-byte scratch buffer for ${chunkRecords} ` +
+          `record(s) of up to ${maxSamplesPerRecord} samples, above the ${budgetBytes}-byte ` +
+          'maxMaterializeBytes budget, so the scan was refused before anything was allocated. ' +
+          'Next: raise options.maxMaterializeBytes, or drop scanSamples and validate the ' +
+          'header alone.',
+        { requiredBytes: scratchBytes, budgetBytes },
+      );
+    }
     scratch = new Int32Array(chunkRecords * maxSamplesPerRecord);
   }
 
@@ -504,7 +529,10 @@ async function traverse(
     bytesRead += bytes.length;
 
     // Never strict: a sweep whose job is to list every defect must not stop at the first one.
-    const decoded = decodeAnnotations(header, bytes, records);
+    // The origin is the recording's, so the sweep's verdict does not depend on its chunk size.
+    const decoded = decodeAnnotations(header, bytes, records, {
+      originTicks: recording.timeline.startOffsetTicks,
+    });
     onsets.set(decoded.recordOnsetTicks, records.start);
     diagnostics.push(...decoded.diagnostics);