edf2csv 0.5.54 → 0.5.55

package/CHANGELOG.md

@@ -3,6 +3,34 @@
 Notable changes to edf2csv. Versions follow [semantic versioning](https://semver.org); while the
 major version is 0, a minor bump may contain breaking changes.
 
+## 0.5.55
+
+### Fixed: a duration that could not be read was exported as a duration nobody wrote
+
+`duration_s` is empty in annotations.csv when the event carries no duration, and the
+documentation says so on three pages. The decoder produced the same empty cell for a TAL that
+stated a duration which is not a number — `Number('abc')` is NaN, NaN became `null`, and
+`null` is what an absent duration is. So
+
+```
+onset_s,duration_s,description,record_index
+0.25,,duration-was-given,0
+0.5,,no-duration-given,0
+```
+
+two rows that the file distinguishes and the CSV does not, with nothing on stderr and no
+diagnostic in metadata.json. The onset is already held to a stricter standard: one that is
+not a number costs the whole TAL and raises ANNOTATION_DECODE_FAILED. A duration is one field
+of an otherwise perfectly readable event, so losing the event over it would be the wrong
+trade — but losing it in silence is not the alternative.
+
+Counted now, and reported: "1 annotation states a duration that is not a number, so its
+duration_s cell is empty", with a hint saying the onset and description were read normally
+and that these rows cannot be told apart from the ones whose file gave no duration. Counted
+per row rather than per TAL, since one TAL may carry several texts and each becomes a row
+with the same empty cell. A recording whose durations are all readable or all absent stays
+silent, which is nearly all of them.
+
 ## 0.5.54
 
 ### Fixed: a recording with no channels was told its channels carry no samples

package/dist/convert/timing.d.ts

@@ -5,6 +5,8 @@ export interface AnnotationTimingData {
     malformed: number;
     /** Unreadable TALs in first position, which carry timing rather than an event. */
     malformedTimekeeping?: number;
+    /** Events kept whose stated duration could not be read. */
+    unreadableDurations?: number;
 }
 /**
  * Resolve the true start time of every data record.

package/dist/convert/timing.js

@@ -16,6 +16,31 @@ export function deriveRecordStarts(file, annotationData) {
             hint: 'The rest were exported normally. The file may have been written by a non-conforming tool.',
         });
     }
+    /*
+      An event that was exported, minus a field.
+  
+      `duration_s` is empty in annotations.csv when the file stated no duration, which is what
+      the documentation says an empty cell means. A duration the file did state and this could
+      not read produced exactly the same empty cell, so an event written with a duration of
+      `abc` was exported as an event that never had one — the same row as its neighbour, and
+      nothing said a field had been dropped.
+  
+      Not counted among the entries that "could not be exported": this one was, and everything
+      else about it is intact. The count is of rows in annotations.csv, since a TAL may carry
+      several texts and each becomes a row with the same empty cell.
+    */
+    const unreadableDurations = annotationData.unreadableDurations ?? 0;
+    if (unreadableDurations > 0) {
+        const one = unreadableDurations === 1;
+        diagnostics.push({
+            code: 'ANNOTATION_DECODE_FAILED',
+            severity: 'warning',
+            message: `${unreadableDurations} annotation${one ? '' : 's'} state${one ? 's' : ''} a duration ` +
+                `that is not a number, so ${one ? 'its' : 'their'} duration_s cell is empty.`,
+            hint: 'The onset and the description were read normally. An empty duration_s otherwise ' +
+                'means the file stated no duration, so these rows cannot be told apart from those.',
+        });
+    }
     /*
       A timekeeping TAL is not an event, and saying it "could not be exported" describes the
       wrong loss twice over.

package/dist/convert/timing.js.map

@@ -1 +1 @@
-{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/convert/timing.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Diagnostic } from '../edf/errors.js';\nimport type { EdfFile } from '../edf/reader.js';\n\nexport interface AnnotationTimingData {\n  recordStarts: (number | null)[];\n  malformed: number;\n  /** Unreadable TALs in first position, which carry timing rather than an event. */\n  malformedTimekeeping?: number;\n}\n\n/**\n * Resolve the true start time of every data record.\n *\n * Continuous recordings need no table because their record positions are\n * arithmetic. EDF+D recordings carry their positions in the annotation channel;\n * missing or malformed timekeeping entries are reported before falling back.\n */\nexport function deriveRecordStarts(\n  file: EdfFile,\n  annotationData: AnnotationTimingData,\n): { starts: Float64Array | null; diagnostics: Diagnostic[] } {\n  const diagnostics: Diagnostic[] = [];\n\n  if (annotationData.malformed > 0) {\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${annotationData.malformed} annotation entr${annotationData.malformed === 1 ? 'y was' : 'ies were'} ` +\n        `unreadable and could not be exported.`,\n      hint: 'The rest were exported normally. The file may have been written by a non-conforming tool.',\n    });\n  }\n\n  /*\n    A timekeeping TAL is not an event, and saying it \"could not be exported\" describes the\n    wrong loss twice over.\n\n    These were counted among the annotations, so a file with one unreadable timekeeping TAL\n    and three good events announced \"1 annotation entry was unreadable and could not be\n    exported\" — while exporting all three. Nothing was missing from annotations.csv; what\n    went missing was a record's position in time, which the message never mentioned.\n  */\n  const lostTimekeeping = annotationData.malformedTimekeeping ?? 0;\n  // The EDF+D branch below raises its own, which names the records and is more specific.\n  // Saying both would report one problem twice.\n  if (lostTimekeeping > 0 && file.header.continuity !== 'EDF+D') {\n    const one = lostTimekeeping === 1;\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${lostTimekeeping} data record${one ? '' : 's'} carr${one ? 'ies' : 'y'} a timekeeping ` +\n        `annotation that could not be read, so ${one ? 'it does' : 'they do'} not say where in ` +\n        `time ${one ? 'it sits' : 'they sit'}.`,\n      hint:\n        'No event was lost — a timekeeping annotation states a record\\'s start time and is ' +\n        'never exported. Times are derived from the records that could be read.',\n    });\n  }\n\n  /*\n    A continuous recording's records are contiguous, but the first one need not sit at zero.\n\n    EDF+ puts the header's start time and every annotation onset on one origin, and says the\n    first data record's timekeeping TAL \"always starts with +0.X\", stating the fraction of a\n    second by which that record follows it. Ignoring that fraction timed the samples from 0\n    while the events kept their true onsets, so the two ended up on origins half a second\n    apart — an event at +0.75 in a 4 Hz recording whose first TAL reads +0.5 landed on sample\n    3 instead of sample 1. The same file marked EDF+D, byte-identical but for the reserved\n    field, placed it correctly, which is what gives the omission away.\n\n    Records stay contiguous, which is what continuous means: only the origin moves. A first\n    TAL of +0 needs no table at all, and that is nearly every file.\n  */\n  if (file.header.continuity !== 'EDF+D') {\n    if (file.header.continuity !== 'EDF+C') return { starts: null, diagnostics };\n\n    /*\n      The origin comes from whichever record first states one, not from record 0 alone.\n\n      Reading only `recordStarts[0]` meant a single unreadable timekeeping TAL threw the\n      origin away and timed the whole file from zero — while records 1 and 2, saying plainly\n      that they start at 1.5s and 2.5s, went unread. A recording whose records sit at 0.5s,\n      1.5s and 2.5s came out with every sample 0.5s earlier than the file states, against\n      annotation onsets that kept their true values. That is precisely the mismatch 0.4.9\n      fixed, arriving through the one hole left in it, and the byte-identical EDF+D twin\n      timed it correctly, which is what gives it away.\n\n      Continuity is what makes this recoverable: record i sits at `origin + i * duration`,\n      so any readable record determines the origin for all of them.\n    */\n    const origin = originOf(annotationData.recordStarts, file.header.recordDuration);\n    if (origin === null) return { starts: null, diagnostics };\n\n    const contiguous = new Float64Array(file.recordCount);\n    for (let i = 0; i < file.recordCount; i++) {\n      contiguous[i] = origin + i * file.header.recordDuration;\n    }\n\n    /*\n      A file marked continuous whose own records disagree about it.\n\n      Nothing looked at records past the first, so an EDF+C file whose records are in fact\n      spread out was timed as though they were contiguous and said nothing. The records are\n      being read here anyway, so the contradiction costs nothing to notice — and it is the\n      file, not the reader, that has to be wrong for this to fire.\n\n      Compared against what the file can express, not for equality. 0.4.41 asked whether the\n      two doubles were the same, which they are not: a recording of 0.1s records sitting at\n      0.1, 0.2, 0.3 ... is contiguous by construction, and 0.1 + 2 * 0.1 is\n      0.30000000000000004. Two of its eight records were reported as contradicting\n      continuity, on an ordinary file — and under --strict that was a failed run. The\n      smallest interval the recording distinguishes is one sample of its fastest channel;\n      anything below half of that is arithmetic, not a gap. `canCarry` has already refused\n      origins where the double spacing swamps that interval, so the representation error is\n      under the tolerance by construction rather than by hope.\n    */\n    const tolerance = finestInterval(file) / 2;\n    const contradicting = annotationData.recordStarts.filter(\n      (declared, i) =>\n        typeof declared === 'number' && Math.abs(declared - (contiguous[i] as number)) > tolerance,\n    ).length;\n    if (contradicting > 0) {\n      diagnostics.push({\n        code: 'DISCONTINUOUS',\n        severity: 'warning',\n        message:\n          `This file is marked continuous (EDF+C), but ${contradicting} of its ` +\n          `${file.recordCount} data records say they start somewhere other than where ` +\n          `continuity puts them.`,\n        hint:\n          'Times are written as if the records were contiguous, which is what EDF+C means. ' +\n          'If the recording really has gaps, the file should have been marked EDF+D.',\n      });\n    }\n    const first = origin;\n    const last = contiguous[file.recordCount - 1] ?? first;\n    if (!canCarry(last, file)) {\n      diagnostics.push(unusableOrigin(first, file));\n      return { starts: null, diagnostics };\n    }\n    /*\n      An origin of zero is the same as no origin, for timing. It is not the same for the\n      check above.\n\n      This returned early on `origin === 0`, which is right about the times — contiguous\n      starts from zero are what timing from zero already produces — and skipped the\n      contradiction check on the way past. So an EDF+C file whose records say 0, 5 and 10 on\n      one-second records went unreported, while the same file shifted one second, saying 1, 6\n      and 11, was reported. The contradiction is in records 1 and 2 either way; where record 0\n      happens to sit decides nothing about it.\n    */\n    if (origin === 0) return { starts: null, diagnostics };\n    return { starts: contiguous, diagnostics };\n  }\n\n  if (file.annotationSignals.length === 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message:\n        'This file is marked discontinuous but has no annotation channel, so where its ' +\n        'records sit in time is not recorded anywhere.',\n      hint: 'Times are written as if the records were contiguous. Any gaps are lost.',\n    });\n    return { starts: null, diagnostics };\n  }\n\n  /*\n    A record with no readable time is placed from the origin the other records establish,\n    not from zero.\n\n    `i * recordDuration` assumed the recording began at zero, which is the one thing the\n    other records are in a position to contradict: a file starting at 0.5s put its\n    unreadable record at 0.000 while its neighbours sat at 1.5s and 2.5s. The guess is still\n    a guess — a discontinuous file may have a gap exactly there — and it is still reported\n    below, but starting it from where the recording actually begins is strictly closer, and\n    it makes an EDF+D file agree with its byte-identical EDF+C twin about record 0.\n  */\n  const base = originOf(annotationData.recordStarts, file.header.recordDuration) ?? 0;\n  const starts = new Float64Array(file.recordCount);\n  const missing: number[] = [];\n  for (let i = 0; i < file.recordCount; i++) {\n    const declared = annotationData.recordStarts[i];\n    if (declared === null || declared === undefined) {\n      missing.push(i);\n      starts[i] = base + i * file.header.recordDuration;\n    } else {\n      starts[i] = declared;\n    }\n  }\n\n  if (missing.length > 0) {\n    const shown = missing.slice(0, 5).join(', ');\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${missing.length} of ${file.recordCount} data records carry no readable timekeeping ` +\n        `annotation (record${missing.length === 1 ? '' : 's'} ${shown}` +\n        `${missing.length > 5 ? ', …' : ''}), so their true position in time is unknown.`,\n      hint: 'Those records are timed as if they were contiguous; treat their timestamps as unreliable.',\n    });\n  }\n\n  /*\n    Furthest from zero, in either direction.\n\n    This took the signed maximum and seeded it with 0, so a recording whose records all sit\n    at negative onsets never got past the seed: `furthest` stayed 0, which any interval can\n    carry. Then the samples collapsed anyway, because the arithmetic that defeats a large\n    positive origin defeats a large negative one identically — at -1e16 seconds, adding a\n    1-second sample interval leaves the double unchanged.\n\n    A four-record recording of eight samples wrote two rows, exit 0, no warning. Its\n    byte-for-byte positive mirror wrote all eight and explained why it had to time them from\n    zero. Same file, same failure, opposite sign, opposite outcome — and the silent one is\n    the one that loses data, which is exactly what unusableOrigin exists to prevent.\n  */\n  let furthest = 0;\n  for (const start of starts) if (Math.abs(start) > Math.abs(furthest)) furthest = start;\n  if (!canCarry(furthest, file)) {\n    diagnostics.push(unusableOrigin(furthest, file));\n    return { starts: null, diagnostics };\n  }\n\n  /*\n    Two ways a record can put the time column out of order, and only one was being looked for.\n\n    A record starting before the one before it is the obvious case. The other is a record\n    starting before the one before it *ends*: starts of 0, 0.5 and 1.0 on one-second records\n    are strictly increasing, so nothing fired, and the rows still came out 0.25, 0.5, 0.75,\n    0.5 — because record 0's samples run to 0.75 while record 1 begins at 0.5. Overlapping\n    acquisition is what a device does when it re-sends a buffer, and the reader has no more\n    to say about it than about the reversed case: every sample is written, in file order,\n    with the time the file gives it.\n\n    Contiguity is not overlap. A continuous recording has `starts[i] === starts[i-1] +\n    duration` exactly, so the comparison is made strict by a fraction of the finest interval\n    the recording can express — the same measure the origin check uses.\n  */\n  const slack = finestInterval(file) / 2;\n  let outOfOrder = 0;\n  let overlapping = 0;\n  for (let i = 1; i < starts.length; i++) {\n    const previous = starts[i - 1] as number;\n    const current = starts[i] as number;\n    if (current < previous) outOfOrder++;\n    else if (current + slack < previous + file.header.recordDuration) overlapping++;\n  }\n  if (outOfOrder > 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message: `${outOfOrder} data record${outOfOrder === 1 ? '' : 's'} start earlier than the record before it.`,\n      hint: 'Rows are written in file order, so the time column will not increase monotonically.',\n    });\n  }\n  if (overlapping > 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message:\n        `${overlapping} data record${overlapping === 1 ? '' : 's'} start before the record ` +\n        `before ${overlapping === 1 ? 'it' : 'them'} ends, so their samples overlap in time.`,\n      hint: 'Rows are written in file order, so the time column will not increase monotonically.',\n    });\n  }\n\n  return { starts, diagnostics };\n}\n\n/**\n * The recording's origin, from the first record that states where it is.\n *\n * Records of a continuous recording sit end to end, so record `i` beginning at `t` puts the\n * origin at `t - i * duration`. Any one readable timekeeping TAL is therefore enough, which\n * is what stops one unreadable entry from costing the whole file its position in time.\n */\nfunction originOf(recordStarts: readonly (number | null)[], recordDuration: number): number | null {\n  for (const [index, declared] of recordStarts.entries()) {\n    if (typeof declared !== 'number') continue;\n    const origin = declared - index * recordDuration;\n    return Number.isFinite(origin) ? origin : null;\n  }\n  return null;\n}\n\n/**\n * Whether times this far out can still tell one sample from the next.\n *\n * A double spaces its values further apart the larger they get: at 1e16 the gap is 2\n * seconds, so `t + 1` is `t`. Past that point a recording's declared origin stops being a\n * position and becomes a wall — the arithmetic that places records and samples returns the\n * origin itself, whatever is added to it.\n *\n * The finest thing that has to survive is the gap between two consecutive samples of the\n * fastest channel, since that is what the time column is made of. If that survives, so does\n * a whole record.\n */\nfunction canCarry(origin: number, file: EdfFile): boolean {\n  if (!Number.isFinite(origin)) return false;\n  // Asked of the origin furthest from zero, whichever side it is on: the spacing of doubles\n  // grows with magnitude, not with value, so -1e16 and +1e16 fail this identically.\n  return origin + finestInterval(file) > origin;\n}\n\n/**\n * The shortest span this recording can tell apart: one sample of its fastest channel.\n *\n * The time column is made of these, so nothing below one is a distinction the file is in a\n * position to make — which is what makes it the right size for both the \"can this origin\n * still separate two samples\" question and the \"is this record really somewhere else\"\n * question.\n */\nfunction finestInterval(file: EdfFile): number {\n  let interval = file.header.recordDuration;\n  for (const signal of file.header.signals) {\n    if (signal.isAnnotations || !(signal.samplesPerRecord > 0)) continue;\n    const step = file.header.recordDuration / signal.samplesPerRecord;\n    if (step > 0 && step < interval) interval = step;\n  }\n  return interval;\n}\n\n/**\n * An origin the file's own arithmetic cannot express, reported rather than acted on.\n *\n * Two things went wrong when this was taken at face value, both of them quiet. A file whose\n * records all collapsed onto one instant made the recording zero seconds long, and the\n * window resolver — which had no reason to suspect the recording rather than the request —\n * blamed a flag nobody had passed:\n *\n *     error: --start 100000000000000000s is at or past the end of this\n *            100000000000000000s recording.\n *\n * Slightly below that, the collapse is partial: `records[i].start + recordDuration` equals\n * the start again, so the test for \"does this record overlap the window\" fails for every\n * record whose neighbour rounded onto it. A twelve-row recording wrote four rows, exit 0,\n * no warning — the eight that vanished looked exactly like a file that never had them.\n *\n * Timing from zero is what the file did before 0.4.9 taught it to honour the first\n * timekeeping TAL, and at this magnitude it is the only column that can hold distinct\n * values. The origin is lost, so this says so.\n */\nfunction unusableOrigin(origin: number, file: EdfFile): Diagnostic {\n  return {\n    code: 'DISCONTINUOUS',\n    severity: 'warning',\n    message:\n      `This recording's timekeeping annotations place it ${origin}s from its own start ` +\n      `date, which is too far out for its ${file.header.recordDuration}s records to be told ` +\n      `apart: at that magnitude adding a sample interval leaves the number unchanged.`,\n    hint:\n      'Sample times are written from zero instead, so every row is present and the column ' +\n      'increases. Add the onsets in annotations.csv to recover absolute times if you need them.',\n  };\n}\n"]}
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/convert/timing.ts"],"names":[],"mappings":"AAYA;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAa,EACb,cAAoC;IAEpC,MAAM,WAAW,GAAiB,EAAE,CAAC;IAErC,IAAI,cAAc,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QACjC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,0BAA0B;YAChC,QAAQ,EAAE,SAAS;YACnB,OAAO,EACL,GAAG,cAAc,CAAC,SAAS,mBAAmB,cAAc,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,GAAG;gBACtG,uCAAuC;YACzC,IAAI,EAAE,2FAA2F;SAClG,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;MAYE;IACF,MAAM,mBAAmB,GAAG,cAAc,CAAC,mBAAmB,IAAI,CAAC,CAAC;IACpE,IAAI,mBAAmB,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,mBAAmB,KAAK,CAAC,CAAC;QACtC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,0BAA0B;YAChC,QAAQ,EAAE,SAAS;YACnB,OAAO,EACL,GAAG,mBAAmB,cAAc,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,cAAc;gBACvF,4BAA4B,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,4BAA4B;YAC/E,IAAI,EACF,kFAAkF;gBAClF,mFAAmF;SACtF,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;MAQE;IACF,MAAM,eAAe,GAAG,cAAc,CAAC,oBAAoB,IAAI,CAAC,CAAC;IACjE,uFAAuF;IACvF,8CAA8C;IAC9C,IAAI,eAAe,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,KAAK,OAAO,EAAE,CAAC;QAC9D,MAAM,GAAG,GAAG,eAAe,KAAK,CAAC,CAAC;QAClC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,0BAA0B;YAChC,QAAQ,EAAE,SAAS;YACnB,OAAO,EACL,GAAG,eAAe,eAAe,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,iBAAiB;gBACzF,yCAAyC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,oBAAoB;gBACxF,QAAQ,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,GAAG;YACzC,IAAI,EACF,oFAAoF;gBACpF,wEAAwE;SAC3E,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;MAaE;IACF,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,KAAK,OAAO,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,KAAK,OAAO;YAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;QAE7E;;;;;;;;;;;;;UAaE;QACF,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QACjF,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;QAE1D,MAAM,UAAU,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACtD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;QAC1D,CAAC;QAED;;;;;;;;;;;;;;;;;UAiBE;QACF,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3C,MAAM,aAAa,GAAG,cAAc,CAAC,YAAY,CAAC,MAAM,CACtD,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CACd,OAAO,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAI,UAAU,CAAC,CAAC,CAAY,CAAC,GAAG,SAAS,CAC7F,CAAC,MAAM,CAAC;QACT,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;YACtB,WAAW,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,eAAe;gBACrB,QAAQ,EAAE,SAAS;gBACnB,OAAO,EACL,+CAA+C,aAAa,UAAU;oBACtE,GAAG,IAAI,CAAC,WAAW,0DAA0D;oBAC7E,uBAAuB;gBACzB,IAAI,EACF,kFAAkF;oBAClF,2EAA2E;aAC9E,CAAC,CAAC;QACL,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC;QACrB,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC;QACvD,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;YAC1B,WAAW,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;YAC9C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;QACvC,CAAC;QACD;;;;;;;;;;UAUE;QACF,IAAI,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;QACvD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;IAC7C,CAAC;IAED,IAAI,IAAI,CAAC,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,eAAe;YACrB,QAAQ,EAAE,SAAS;YACnB,OAAO,EACL,gFAAgF;gBAChF,+CAA+C;YACjD,IAAI,EAAE,yEAAyE;SAChF,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACvC,CAAC;IAED;;;;;;;;;;MAUE;IACF,MAAM,IAAI,GAAG,QAAQ,CAAC,cAAc,CAAC,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IACpF,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAClD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,QAAQ,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAChD,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC;QACvB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,0BAA0B;YAChC,QAAQ,EAAE,SAAS;YACnB,OAAO,EACL,GAAG,OAAO,CAAC,MAAM,OAAO,IAAI,CAAC,WAAW,8CAA8C;gBACtF,qBAAqB,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,EAAE;gBAC/D,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,+CAA+C;YACnF,IAAI,EAAE,2FAA2F;SAClG,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;MAaE;IACF,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,QAAQ,GAAG,KAAK,CAAC;IACvF,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;QAC9B,WAAW,CAAC,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;QACjD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACvC,CAAC;IAED;;;;;;;;;;;;;;MAcE;IACF,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAW,CAAC;QACzC,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAW,CAAC;QACpC,IAAI,OAAO,GAAG,QAAQ;YAAE,UAAU,EAAE,CAAC;aAChC,IAAI,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc;YAAE,WAAW,EAAE,CAAC;IAClF,CAAC;IACD,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,eAAe;YACrB,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,GAAG,UAAU,eAAe,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,2CAA2C;YAC3G,IAAI,EAAE,qFAAqF;SAC5F,CAAC,CAAC;IACL,CAAC;IACD,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACpB,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,eAAe;YACrB,QAAQ,EAAE,SAAS;YACnB,OAAO,EACL,GAAG,WAAW,eAAe,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,2BAA2B;gBACpF,UAAU,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,0CAA0C;YACvF,IAAI,EAAE,qFAAqF;SAC5F,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,QAAQ,CAAC,YAAwC,EAAE,cAAsB;IAChF,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,OAAO,QAAQ,KAAK,QAAQ;YAAE,SAAS;QAC3C,MAAM,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,cAAc,CAAC;QACjD,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,QAAQ,CAAC,MAAc,EAAE,IAAa;IAC7C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,0FAA0F;IAC1F,kFAAkF;IAClF,OAAO,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;AAChD,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,IAAa;IACnC,IAAI,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;IAC1C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACzC,IAAI,MAAM,CAAC,aAAa,IAAI,CAAC,CAAC,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC;YAAE,SAAS;QACrE,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,GAAG,MAAM,CAAC,gBAAgB,CAAC;QAClE,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,QAAQ;YAAE,QAAQ,GAAG,IAAI,CAAC;IACnD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,cAAc,CAAC,MAAc,EAAE,IAAa;IACnD,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,QAAQ,EAAE,SAAS;QACnB,OAAO,EACL,qDAAqD,MAAM,uBAAuB;YAClF,sCAAsC,IAAI,CAAC,MAAM,CAAC,cAAc,uBAAuB;YACvF,gFAAgF;QAClF,IAAI,EACF,qFAAqF;YACrF,0FAA0F;KAC7F,CAAC;AACJ,CAAC","sourcesContent":["import type { Diagnostic } from '../edf/errors.js';\nimport type { EdfFile } from '../edf/reader.js';\n\nexport interface AnnotationTimingData {\n  recordStarts: (number | null)[];\n  malformed: number;\n  /** Unreadable TALs in first position, which carry timing rather than an event. */\n  malformedTimekeeping?: number;\n  /** Events kept whose stated duration could not be read. */\n  unreadableDurations?: number;\n}\n\n/**\n * Resolve the true start time of every data record.\n *\n * Continuous recordings need no table because their record positions are\n * arithmetic. EDF+D recordings carry their positions in the annotation channel;\n * missing or malformed timekeeping entries are reported before falling back.\n */\nexport function deriveRecordStarts(\n  file: EdfFile,\n  annotationData: AnnotationTimingData,\n): { starts: Float64Array | null; diagnostics: Diagnostic[] } {\n  const diagnostics: Diagnostic[] = [];\n\n  if (annotationData.malformed > 0) {\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${annotationData.malformed} annotation entr${annotationData.malformed === 1 ? 'y was' : 'ies were'} ` +\n        `unreadable and could not be exported.`,\n      hint: 'The rest were exported normally. The file may have been written by a non-conforming tool.',\n    });\n  }\n\n  /*\n    An event that was exported, minus a field.\n\n    `duration_s` is empty in annotations.csv when the file stated no duration, which is what\n    the documentation says an empty cell means. A duration the file did state and this could\n    not read produced exactly the same empty cell, so an event written with a duration of\n    `abc` was exported as an event that never had one — the same row as its neighbour, and\n    nothing said a field had been dropped.\n\n    Not counted among the entries that \"could not be exported\": this one was, and everything\n    else about it is intact. The count is of rows in annotations.csv, since a TAL may carry\n    several texts and each becomes a row with the same empty cell.\n  */\n  const unreadableDurations = annotationData.unreadableDurations ?? 0;\n  if (unreadableDurations > 0) {\n    const one = unreadableDurations === 1;\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${unreadableDurations} annotation${one ? '' : 's'} state${one ? 's' : ''} a duration ` +\n        `that is not a number, so ${one ? 'its' : 'their'} duration_s cell is empty.`,\n      hint:\n        'The onset and the description were read normally. An empty duration_s otherwise ' +\n        'means the file stated no duration, so these rows cannot be told apart from those.',\n    });\n  }\n\n  /*\n    A timekeeping TAL is not an event, and saying it \"could not be exported\" describes the\n    wrong loss twice over.\n\n    These were counted among the annotations, so a file with one unreadable timekeeping TAL\n    and three good events announced \"1 annotation entry was unreadable and could not be\n    exported\" — while exporting all three. Nothing was missing from annotations.csv; what\n    went missing was a record's position in time, which the message never mentioned.\n  */\n  const lostTimekeeping = annotationData.malformedTimekeeping ?? 0;\n  // The EDF+D branch below raises its own, which names the records and is more specific.\n  // Saying both would report one problem twice.\n  if (lostTimekeeping > 0 && file.header.continuity !== 'EDF+D') {\n    const one = lostTimekeeping === 1;\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${lostTimekeeping} data record${one ? '' : 's'} carr${one ? 'ies' : 'y'} a timekeeping ` +\n        `annotation that could not be read, so ${one ? 'it does' : 'they do'} not say where in ` +\n        `time ${one ? 'it sits' : 'they sit'}.`,\n      hint:\n        'No event was lost — a timekeeping annotation states a record\\'s start time and is ' +\n        'never exported. Times are derived from the records that could be read.',\n    });\n  }\n\n  /*\n    A continuous recording's records are contiguous, but the first one need not sit at zero.\n\n    EDF+ puts the header's start time and every annotation onset on one origin, and says the\n    first data record's timekeeping TAL \"always starts with +0.X\", stating the fraction of a\n    second by which that record follows it. Ignoring that fraction timed the samples from 0\n    while the events kept their true onsets, so the two ended up on origins half a second\n    apart — an event at +0.75 in a 4 Hz recording whose first TAL reads +0.5 landed on sample\n    3 instead of sample 1. The same file marked EDF+D, byte-identical but for the reserved\n    field, placed it correctly, which is what gives the omission away.\n\n    Records stay contiguous, which is what continuous means: only the origin moves. A first\n    TAL of +0 needs no table at all, and that is nearly every file.\n  */\n  if (file.header.continuity !== 'EDF+D') {\n    if (file.header.continuity !== 'EDF+C') return { starts: null, diagnostics };\n\n    /*\n      The origin comes from whichever record first states one, not from record 0 alone.\n\n      Reading only `recordStarts[0]` meant a single unreadable timekeeping TAL threw the\n      origin away and timed the whole file from zero — while records 1 and 2, saying plainly\n      that they start at 1.5s and 2.5s, went unread. A recording whose records sit at 0.5s,\n      1.5s and 2.5s came out with every sample 0.5s earlier than the file states, against\n      annotation onsets that kept their true values. That is precisely the mismatch 0.4.9\n      fixed, arriving through the one hole left in it, and the byte-identical EDF+D twin\n      timed it correctly, which is what gives it away.\n\n      Continuity is what makes this recoverable: record i sits at `origin + i * duration`,\n      so any readable record determines the origin for all of them.\n    */\n    const origin = originOf(annotationData.recordStarts, file.header.recordDuration);\n    if (origin === null) return { starts: null, diagnostics };\n\n    const contiguous = new Float64Array(file.recordCount);\n    for (let i = 0; i < file.recordCount; i++) {\n      contiguous[i] = origin + i * file.header.recordDuration;\n    }\n\n    /*\n      A file marked continuous whose own records disagree about it.\n\n      Nothing looked at records past the first, so an EDF+C file whose records are in fact\n      spread out was timed as though they were contiguous and said nothing. The records are\n      being read here anyway, so the contradiction costs nothing to notice — and it is the\n      file, not the reader, that has to be wrong for this to fire.\n\n      Compared against what the file can express, not for equality. 0.4.41 asked whether the\n      two doubles were the same, which they are not: a recording of 0.1s records sitting at\n      0.1, 0.2, 0.3 ... is contiguous by construction, and 0.1 + 2 * 0.1 is\n      0.30000000000000004. Two of its eight records were reported as contradicting\n      continuity, on an ordinary file — and under --strict that was a failed run. The\n      smallest interval the recording distinguishes is one sample of its fastest channel;\n      anything below half of that is arithmetic, not a gap. `canCarry` has already refused\n      origins where the double spacing swamps that interval, so the representation error is\n      under the tolerance by construction rather than by hope.\n    */\n    const tolerance = finestInterval(file) / 2;\n    const contradicting = annotationData.recordStarts.filter(\n      (declared, i) =>\n        typeof declared === 'number' && Math.abs(declared - (contiguous[i] as number)) > tolerance,\n    ).length;\n    if (contradicting > 0) {\n      diagnostics.push({\n        code: 'DISCONTINUOUS',\n        severity: 'warning',\n        message:\n          `This file is marked continuous (EDF+C), but ${contradicting} of its ` +\n          `${file.recordCount} data records say they start somewhere other than where ` +\n          `continuity puts them.`,\n        hint:\n          'Times are written as if the records were contiguous, which is what EDF+C means. ' +\n          'If the recording really has gaps, the file should have been marked EDF+D.',\n      });\n    }\n    const first = origin;\n    const last = contiguous[file.recordCount - 1] ?? first;\n    if (!canCarry(last, file)) {\n      diagnostics.push(unusableOrigin(first, file));\n      return { starts: null, diagnostics };\n    }\n    /*\n      An origin of zero is the same as no origin, for timing. It is not the same for the\n      check above.\n\n      This returned early on `origin === 0`, which is right about the times — contiguous\n      starts from zero are what timing from zero already produces — and skipped the\n      contradiction check on the way past. So an EDF+C file whose records say 0, 5 and 10 on\n      one-second records went unreported, while the same file shifted one second, saying 1, 6\n      and 11, was reported. The contradiction is in records 1 and 2 either way; where record 0\n      happens to sit decides nothing about it.\n    */\n    if (origin === 0) return { starts: null, diagnostics };\n    return { starts: contiguous, diagnostics };\n  }\n\n  if (file.annotationSignals.length === 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message:\n        'This file is marked discontinuous but has no annotation channel, so where its ' +\n        'records sit in time is not recorded anywhere.',\n      hint: 'Times are written as if the records were contiguous. Any gaps are lost.',\n    });\n    return { starts: null, diagnostics };\n  }\n\n  /*\n    A record with no readable time is placed from the origin the other records establish,\n    not from zero.\n\n    `i * recordDuration` assumed the recording began at zero, which is the one thing the\n    other records are in a position to contradict: a file starting at 0.5s put its\n    unreadable record at 0.000 while its neighbours sat at 1.5s and 2.5s. The guess is still\n    a guess — a discontinuous file may have a gap exactly there — and it is still reported\n    below, but starting it from where the recording actually begins is strictly closer, and\n    it makes an EDF+D file agree with its byte-identical EDF+C twin about record 0.\n  */\n  const base = originOf(annotationData.recordStarts, file.header.recordDuration) ?? 0;\n  const starts = new Float64Array(file.recordCount);\n  const missing: number[] = [];\n  for (let i = 0; i < file.recordCount; i++) {\n    const declared = annotationData.recordStarts[i];\n    if (declared === null || declared === undefined) {\n      missing.push(i);\n      starts[i] = base + i * file.header.recordDuration;\n    } else {\n      starts[i] = declared;\n    }\n  }\n\n  if (missing.length > 0) {\n    const shown = missing.slice(0, 5).join(', ');\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${missing.length} of ${file.recordCount} data records carry no readable timekeeping ` +\n        `annotation (record${missing.length === 1 ? '' : 's'} ${shown}` +\n        `${missing.length > 5 ? ', …' : ''}), so their true position in time is unknown.`,\n      hint: 'Those records are timed as if they were contiguous; treat their timestamps as unreliable.',\n    });\n  }\n\n  /*\n    Furthest from zero, in either direction.\n\n    This took the signed maximum and seeded it with 0, so a recording whose records all sit\n    at negative onsets never got past the seed: `furthest` stayed 0, which any interval can\n    carry. Then the samples collapsed anyway, because the arithmetic that defeats a large\n    positive origin defeats a large negative one identically — at -1e16 seconds, adding a\n    1-second sample interval leaves the double unchanged.\n\n    A four-record recording of eight samples wrote two rows, exit 0, no warning. Its\n    byte-for-byte positive mirror wrote all eight and explained why it had to time them from\n    zero. Same file, same failure, opposite sign, opposite outcome — and the silent one is\n    the one that loses data, which is exactly what unusableOrigin exists to prevent.\n  */\n  let furthest = 0;\n  for (const start of starts) if (Math.abs(start) > Math.abs(furthest)) furthest = start;\n  if (!canCarry(furthest, file)) {\n    diagnostics.push(unusableOrigin(furthest, file));\n    return { starts: null, diagnostics };\n  }\n\n  /*\n    Two ways a record can put the time column out of order, and only one was being looked for.\n\n    A record starting before the one before it is the obvious case. The other is a record\n    starting before the one before it *ends*: starts of 0, 0.5 and 1.0 on one-second records\n    are strictly increasing, so nothing fired, and the rows still came out 0.25, 0.5, 0.75,\n    0.5 — because record 0's samples run to 0.75 while record 1 begins at 0.5. Overlapping\n    acquisition is what a device does when it re-sends a buffer, and the reader has no more\n    to say about it than about the reversed case: every sample is written, in file order,\n    with the time the file gives it.\n\n    Contiguity is not overlap. A continuous recording has `starts[i] === starts[i-1] +\n    duration` exactly, so the comparison is made strict by a fraction of the finest interval\n    the recording can express — the same measure the origin check uses.\n  */\n  const slack = finestInterval(file) / 2;\n  let outOfOrder = 0;\n  let overlapping = 0;\n  for (let i = 1; i < starts.length; i++) {\n    const previous = starts[i - 1] as number;\n    const current = starts[i] as number;\n    if (current < previous) outOfOrder++;\n    else if (current + slack < previous + file.header.recordDuration) overlapping++;\n  }\n  if (outOfOrder > 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message: `${outOfOrder} data record${outOfOrder === 1 ? '' : 's'} start earlier than the record before it.`,\n      hint: 'Rows are written in file order, so the time column will not increase monotonically.',\n    });\n  }\n  if (overlapping > 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message:\n        `${overlapping} data record${overlapping === 1 ? '' : 's'} start before the record ` +\n        `before ${overlapping === 1 ? 'it' : 'them'} ends, so their samples overlap in time.`,\n      hint: 'Rows are written in file order, so the time column will not increase monotonically.',\n    });\n  }\n\n  return { starts, diagnostics };\n}\n\n/**\n * The recording's origin, from the first record that states where it is.\n *\n * Records of a continuous recording sit end to end, so record `i` beginning at `t` puts the\n * origin at `t - i * duration`. Any one readable timekeeping TAL is therefore enough, which\n * is what stops one unreadable entry from costing the whole file its position in time.\n */\nfunction originOf(recordStarts: readonly (number | null)[], recordDuration: number): number | null {\n  for (const [index, declared] of recordStarts.entries()) {\n    if (typeof declared !== 'number') continue;\n    const origin = declared - index * recordDuration;\n    return Number.isFinite(origin) ? origin : null;\n  }\n  return null;\n}\n\n/**\n * Whether times this far out can still tell one sample from the next.\n *\n * A double spaces its values further apart the larger they get: at 1e16 the gap is 2\n * seconds, so `t + 1` is `t`. Past that point a recording's declared origin stops being a\n * position and becomes a wall — the arithmetic that places records and samples returns the\n * origin itself, whatever is added to it.\n *\n * The finest thing that has to survive is the gap between two consecutive samples of the\n * fastest channel, since that is what the time column is made of. If that survives, so does\n * a whole record.\n */\nfunction canCarry(origin: number, file: EdfFile): boolean {\n  if (!Number.isFinite(origin)) return false;\n  // Asked of the origin furthest from zero, whichever side it is on: the spacing of doubles\n  // grows with magnitude, not with value, so -1e16 and +1e16 fail this identically.\n  return origin + finestInterval(file) > origin;\n}\n\n/**\n * The shortest span this recording can tell apart: one sample of its fastest channel.\n *\n * The time column is made of these, so nothing below one is a distinction the file is in a\n * position to make — which is what makes it the right size for both the \"can this origin\n * still separate two samples\" question and the \"is this record really somewhere else\"\n * question.\n */\nfunction finestInterval(file: EdfFile): number {\n  let interval = file.header.recordDuration;\n  for (const signal of file.header.signals) {\n    if (signal.isAnnotations || !(signal.samplesPerRecord > 0)) continue;\n    const step = file.header.recordDuration / signal.samplesPerRecord;\n    if (step > 0 && step < interval) interval = step;\n  }\n  return interval;\n}\n\n/**\n * An origin the file's own arithmetic cannot express, reported rather than acted on.\n *\n * Two things went wrong when this was taken at face value, both of them quiet. A file whose\n * records all collapsed onto one instant made the recording zero seconds long, and the\n * window resolver — which had no reason to suspect the recording rather than the request —\n * blamed a flag nobody had passed:\n *\n *     error: --start 100000000000000000s is at or past the end of this\n *            100000000000000000s recording.\n *\n * Slightly below that, the collapse is partial: `records[i].start + recordDuration` equals\n * the start again, so the test for \"does this record overlap the window\" fails for every\n * record whose neighbour rounded onto it. A twelve-row recording wrote four rows, exit 0,\n * no warning — the eight that vanished looked exactly like a file that never had them.\n *\n * Timing from zero is what the file did before 0.4.9 taught it to honour the first\n * timekeeping TAL, and at this magnitude it is the only column that can hold distinct\n * values. The origin is lost, so this says so.\n */\nfunction unusableOrigin(origin: number, file: EdfFile): Diagnostic {\n  return {\n    code: 'DISCONTINUOUS',\n    severity: 'warning',\n    message:\n      `This recording's timekeeping annotations place it ${origin}s from its own start ` +\n      `date, which is too far out for its ${file.header.recordDuration}s records to be told ` +\n      `apart: at that magnitude adding a sample interval leaves the number unchanged.`,\n    hint:\n      'Sample times are written from zero instead, so every row is present and the column ' +\n      'increases. Add the onsets in annotations.csv to recover absolute times if you need them.',\n  };\n}\n"]}

package/dist/edf/annotations.d.ts

@@ -18,7 +18,14 @@ declare const TAL_END = 0;
 export interface Annotation {
     /** Seconds from the start of the recording. */
     onset: number;
-    /** Seconds, or null when the TAL omitted a duration. */
+    /**
+     * Seconds, or null when the TAL stated no duration that could be read.
+     *
+     * Null covers two cases the file distinguishes and this field does not: a TAL that omitted
+     * the duration, and a TAL that stated one which is not a number. They are told apart by
+     * `unreadableDurations`, which is what raises the warning; the value itself has nowhere
+     * honest to put "the file said `abc`".
+     */
     duration: number | null;
     text: string;
     /** Index of the data record this annotation was stored in. */
@@ -32,6 +39,14 @@ export interface DecodedRecordAnnotations {
     malformed: number;
     /** Unreadable TALs in first position, which carry a record's start time, not an event. */
     malformedTimekeeping: number;
+    /**
+     * Events kept whose stated duration could not be read.
+     *
+     * Counted apart again, for the same reason the two above are: the entry was exported and
+     * nothing about it is missing except the one field, so calling it an entry that "could not
+     * be exported" describes a loss that did not happen and hides the one that did.
+     */
+    unreadableDurations: number;
 }
 /**
  * Decode one data record's annotation bytes.

package/dist/edf/annotations.js

@@ -31,6 +31,7 @@ export function decodeRecordAnnotations(bytes, recordIndex, carriesTimekeeping =
     let isFirstTal = true;
     let malformed = 0;
     let malformedTimekeeping = 0;
+    let unreadableDurations = 0;
     let start = 0;
     for (let i = 0; i <= bytes.length; i++) {
         if (i !== bytes.length && bytes[i] !== TAL_END)
@@ -61,6 +62,7 @@ export function decodeRecordAnnotations(bytes, recordIndex, carriesTimekeeping =
                     recordStart = parsed.onset;
                 for (const annotation of parsed.annotations)
                     annotations.push(annotation);
+                unreadableDurations += parsed.unreadableDurations;
             }
             else {
                 /*
@@ -81,7 +83,7 @@ export function decodeRecordAnnotations(bytes, recordIndex, carriesTimekeeping =
         }
         start = i + 1;
     }
-    return { recordStart, annotations, malformed, malformedTimekeeping };
+    return { recordStart, annotations, malformed, malformedTimekeeping, unreadableDurations };
 }
 function parseTal(chunk, recordIndex) {
     // The onset must be explicitly signed; anything else is not a TAL.
@@ -101,10 +103,25 @@ function parseTal(chunk, recordIndex) {
     const onset = Number(onsetText);
     if (!Number.isFinite(onset))
         return null;
+    /*
+      A duration the file stated and this could not read is not the same as no duration.
+  
+      Both came out as `null` and so as an empty `duration_s` cell, which the documentation
+      defines as meaning the file gave no duration — so an event whose duration was written as
+      `abc` was exported as an event with no duration, indistinguishable from one beside it
+      that genuinely had none, and nothing anywhere said a field had been dropped. The onset is
+      already held to this standard: one that is not a number costs the whole TAL and is
+      reported. A duration is one field of an otherwise readable event, so the event is kept —
+      but it is counted, and the run says so.
+    */
     let duration = null;
+    let durationUnreadable = false;
     if (durationText !== null && durationText !== '') {
         const d = Number(durationText);
-        duration = Number.isFinite(d) ? d : null;
+        if (Number.isFinite(d))
+            duration = d;
+        else
+            durationUnreadable = true;
     }
     const annotations = [];
     for (const raw of parts.slice(1)) {
@@ -113,7 +130,9 @@ function parseTal(chunk, recordIndex) {
             continue;
         annotations.push({ onset, duration, text: raw, recordIndex });
     }
-    return { onset, annotations };
+    // Per event rather than per TAL: one TAL may carry several texts, and each becomes a row
+    // of annotations.csv with the same empty cell in it.
+    return { onset, annotations, unreadableDurations: durationUnreadable ? annotations.length : 0 };
 }
 export { SEP_TEXT, SEP_DURATION, TAL_END };
 //# sourceMappingURL=annotations.js.map

package/dist/edf/annotations.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/edf/annotations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * EDF+ annotation (TAL) decoding.\n *\n * The annotations channel stores UTF-8 text in place of samples. Its bytes are a\n * run of Time-stamped Annotation Lists, each terminated by a NUL, with the rest\n * of the channel NUL-padded:\n *\n *   +<onset>[<0x15><duration>]<0x14><text><0x14>...<0x00>\n *\n * The first TAL of every data record must carry that record's start time and no\n * text; that is how an EDF+D file states where each record actually sits in time.\n *\n *   +1.25<0x15>0.5<0x14>Seizure onset<0x14><0x00>\n */\n\nimport { decodeUtf8 } from './bytes.js';\n\nconst SEP_TEXT = 0x14; // separates onset/duration from text, and text from text\nconst SEP_DURATION = 0x15; // separates onset from duration\nconst TAL_END = 0x00;\n\nconst TEXT_SEP_CHAR = String.fromCharCode(SEP_TEXT);\nconst DURATION_SEP_CHAR = String.fromCharCode(SEP_DURATION);\n\nexport interface Annotation {\n  /** Seconds from the start of the recording. */\n  onset: number;\n  /** Seconds, or null when the TAL omitted a duration. */\n  duration: number | null;\n  text: string;\n  /** Index of the data record this annotation was stored in. */\n  recordIndex: number;\n}\n\nexport interface DecodedRecordAnnotations {\n  /** Record start time in seconds, from the leading timekeeping TAL. */\n  recordStart: number | null;\n  annotations: Annotation[];\n  /** Non-empty chunks that were not valid TALs, so the caller can report them. */\n  malformed: number;\n  /** Unreadable TALs in first position, which carry a record's start time, not an event. */\n  malformedTimekeeping: number;\n}\n\n/**\n * Decode one data record's annotation bytes.\n *\n * Malformed TALs are skipped rather than thrown, because a single bad annotation\n * should not cost the user an entire conversion. The count of skipped chunks is\n * returned so the caller can tell the user rather than losing them in silence.\n */\nexport function decodeRecordAnnotations(\n  bytes: Uint8Array,\n  recordIndex: number,\n  carriesTimekeeping = true,\n): DecodedRecordAnnotations {\n  const annotations: Annotation[] = [];\n  let recordStart: number | null = null;\n  let isFirstTal = true;\n  let malformed = 0;\n  let malformedTimekeeping = 0;\n\n  let start = 0;\n  for (let i = 0; i <= bytes.length; i++) {\n    if (i !== bytes.length && bytes[i] !== TAL_END) continue;\n\n    if (i > start) {\n      const chunk = bytes.subarray(start, i);\n      const parsed = parseTal(chunk, recordIndex);\n\n      // The timekeeping TAL is the one in first POSITION, whether or not it decodes.\n      // Clearing this flag only on a successful parse meant that an unreadable first TAL\n      // promoted the next ordinary annotation to timekeeping, and its onset silently\n      // became the record's start time — shifting every sample in that record. Leaving\n      // recordStart null instead is what the caller already handles, with a fallback\n      // timestamp and an ANNOTATION_DECODE_FAILED warning naming the record.\n      /*\n        Only one annotation channel carries a record's start time.\n\n        This flagged the first TAL of *every* annotation channel as timekeeping. In a second\n        channel the first TAL is an ordinary event — so when one failed to parse, the event\n        was dropped and counted as a lost timekeeping entry, which produced the warning\n        \"3 data records carry a timekeeping annotation that could not be read\" followed by\n        \"No event was lost\". Three events had been lost, and the timekeeping in that file was\n        perfectly readable. Both sentences false, about the same three records.\n      */\n      const isTimekeeping = isFirstTal && carriesTimekeeping;\n      isFirstTal = false;\n\n      if (parsed) {\n        if (isTimekeeping) recordStart = parsed.onset;\n        for (const annotation of parsed.annotations) annotations.push(annotation);\n      } else {\n        /*\n          Counted apart from the events, because losing one is a different loss.\n\n          A timekeeping TAL is never exported — it says where the record sits, not what\n          happened — so counting it among the entries that \"could not be exported\" both\n          overstated what was lost from annotations.csv and said nothing about the thing that\n          actually went missing, which is a record's position in time. A file with one\n          unreadable timekeeping TAL and three perfectly good events reported \"1 annotation\n          entry was unreadable and could not be exported\" while exporting all three.\n        */\n        if (isTimekeeping) malformedTimekeeping++;\n        else malformed++;\n      }\n    }\n    start = i + 1;\n  }\n\n  return { recordStart, annotations, malformed, malformedTimekeeping };\n}\n\ninterface ParsedTal {\n  onset: number;\n  annotations: Annotation[];\n}\n\nfunction parseTal(chunk: Uint8Array, recordIndex: number): ParsedTal | null {\n  // The onset must be explicitly signed; anything else is not a TAL.\n  const first = chunk[0];\n  if (first !== 0x2b /* + */ && first !== 0x2d /* - */) return null;\n\n  const text = decodeUtf8(chunk);\n  const parts = text.split(TEXT_SEP_CHAR);\n  const head = parts[0] ?? '';\n\n  let onsetText = head;\n  let durationText: string | null = null;\n  const durationSep = head.indexOf(DURATION_SEP_CHAR);\n  if (durationSep >= 0) {\n    onsetText = head.slice(0, durationSep);\n    durationText = head.slice(durationSep + 1);\n  }\n\n  const onset = Number(onsetText);\n  if (!Number.isFinite(onset)) return null;\n\n  let duration: number | null = null;\n  if (durationText !== null && durationText !== '') {\n    const d = Number(durationText);\n    duration = Number.isFinite(d) ? d : null;\n  }\n\n  const annotations: Annotation[] = [];\n  for (const raw of parts.slice(1)) {\n    // A trailing separator yields an empty segment; a timekeeping TAL is all empty.\n    if (raw === '') continue;\n    annotations.push({ onset, duration, text: raw, recordIndex });\n  }\n\n  return { onset, annotations };\n}\n\nexport { SEP_TEXT, SEP_DURATION, TAL_END };\n"]}
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/edf/annotations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * EDF+ annotation (TAL) decoding.\n *\n * The annotations channel stores UTF-8 text in place of samples. Its bytes are a\n * run of Time-stamped Annotation Lists, each terminated by a NUL, with the rest\n * of the channel NUL-padded:\n *\n *   +<onset>[<0x15><duration>]<0x14><text><0x14>...<0x00>\n *\n * The first TAL of every data record must carry that record's start time and no\n * text; that is how an EDF+D file states where each record actually sits in time.\n *\n *   +1.25<0x15>0.5<0x14>Seizure onset<0x14><0x00>\n */\n\nimport { decodeUtf8 } from './bytes.js';\n\nconst SEP_TEXT = 0x14; // separates onset/duration from text, and text from text\nconst SEP_DURATION = 0x15; // separates onset from duration\nconst TAL_END = 0x00;\n\nconst TEXT_SEP_CHAR = String.fromCharCode(SEP_TEXT);\nconst DURATION_SEP_CHAR = String.fromCharCode(SEP_DURATION);\n\nexport interface Annotation {\n  /** Seconds from the start of the recording. */\n  onset: number;\n  /**\n   * Seconds, or null when the TAL stated no duration that could be read.\n   *\n   * Null covers two cases the file distinguishes and this field does not: a TAL that omitted\n   * the duration, and a TAL that stated one which is not a number. They are told apart by\n   * `unreadableDurations`, which is what raises the warning; the value itself has nowhere\n   * honest to put \"the file said `abc`\".\n   */\n  duration: number | null;\n  text: string;\n  /** Index of the data record this annotation was stored in. */\n  recordIndex: number;\n}\n\nexport interface DecodedRecordAnnotations {\n  /** Record start time in seconds, from the leading timekeeping TAL. */\n  recordStart: number | null;\n  annotations: Annotation[];\n  /** Non-empty chunks that were not valid TALs, so the caller can report them. */\n  malformed: number;\n  /** Unreadable TALs in first position, which carry a record's start time, not an event. */\n  malformedTimekeeping: number;\n  /**\n   * Events kept whose stated duration could not be read.\n   *\n   * Counted apart again, for the same reason the two above are: the entry was exported and\n   * nothing about it is missing except the one field, so calling it an entry that \"could not\n   * be exported\" describes a loss that did not happen and hides the one that did.\n   */\n  unreadableDurations: number;\n}\n\n/**\n * Decode one data record's annotation bytes.\n *\n * Malformed TALs are skipped rather than thrown, because a single bad annotation\n * should not cost the user an entire conversion. The count of skipped chunks is\n * returned so the caller can tell the user rather than losing them in silence.\n */\nexport function decodeRecordAnnotations(\n  bytes: Uint8Array,\n  recordIndex: number,\n  carriesTimekeeping = true,\n): DecodedRecordAnnotations {\n  const annotations: Annotation[] = [];\n  let recordStart: number | null = null;\n  let isFirstTal = true;\n  let malformed = 0;\n  let malformedTimekeeping = 0;\n  let unreadableDurations = 0;\n\n  let start = 0;\n  for (let i = 0; i <= bytes.length; i++) {\n    if (i !== bytes.length && bytes[i] !== TAL_END) continue;\n\n    if (i > start) {\n      const chunk = bytes.subarray(start, i);\n      const parsed = parseTal(chunk, recordIndex);\n\n      // The timekeeping TAL is the one in first POSITION, whether or not it decodes.\n      // Clearing this flag only on a successful parse meant that an unreadable first TAL\n      // promoted the next ordinary annotation to timekeeping, and its onset silently\n      // became the record's start time — shifting every sample in that record. Leaving\n      // recordStart null instead is what the caller already handles, with a fallback\n      // timestamp and an ANNOTATION_DECODE_FAILED warning naming the record.\n      /*\n        Only one annotation channel carries a record's start time.\n\n        This flagged the first TAL of *every* annotation channel as timekeeping. In a second\n        channel the first TAL is an ordinary event — so when one failed to parse, the event\n        was dropped and counted as a lost timekeeping entry, which produced the warning\n        \"3 data records carry a timekeeping annotation that could not be read\" followed by\n        \"No event was lost\". Three events had been lost, and the timekeeping in that file was\n        perfectly readable. Both sentences false, about the same three records.\n      */\n      const isTimekeeping = isFirstTal && carriesTimekeeping;\n      isFirstTal = false;\n\n      if (parsed) {\n        if (isTimekeeping) recordStart = parsed.onset;\n        for (const annotation of parsed.annotations) annotations.push(annotation);\n        unreadableDurations += parsed.unreadableDurations;\n      } else {\n        /*\n          Counted apart from the events, because losing one is a different loss.\n\n          A timekeeping TAL is never exported — it says where the record sits, not what\n          happened — so counting it among the entries that \"could not be exported\" both\n          overstated what was lost from annotations.csv and said nothing about the thing that\n          actually went missing, which is a record's position in time. A file with one\n          unreadable timekeeping TAL and three perfectly good events reported \"1 annotation\n          entry was unreadable and could not be exported\" while exporting all three.\n        */\n        if (isTimekeeping) malformedTimekeeping++;\n        else malformed++;\n      }\n    }\n    start = i + 1;\n  }\n\n  return { recordStart, annotations, malformed, malformedTimekeeping, unreadableDurations };\n}\n\ninterface ParsedTal {\n  onset: number;\n  annotations: Annotation[];\n  /** How many of those annotations carry a duration the file stated and this could not read. */\n  unreadableDurations: number;\n}\n\nfunction parseTal(chunk: Uint8Array, recordIndex: number): ParsedTal | null {\n  // The onset must be explicitly signed; anything else is not a TAL.\n  const first = chunk[0];\n  if (first !== 0x2b /* + */ && first !== 0x2d /* - */) return null;\n\n  const text = decodeUtf8(chunk);\n  const parts = text.split(TEXT_SEP_CHAR);\n  const head = parts[0] ?? '';\n\n  let onsetText = head;\n  let durationText: string | null = null;\n  const durationSep = head.indexOf(DURATION_SEP_CHAR);\n  if (durationSep >= 0) {\n    onsetText = head.slice(0, durationSep);\n    durationText = head.slice(durationSep + 1);\n  }\n\n  const onset = Number(onsetText);\n  if (!Number.isFinite(onset)) return null;\n\n  /*\n    A duration the file stated and this could not read is not the same as no duration.\n\n    Both came out as `null` and so as an empty `duration_s` cell, which the documentation\n    defines as meaning the file gave no duration — so an event whose duration was written as\n    `abc` was exported as an event with no duration, indistinguishable from one beside it\n    that genuinely had none, and nothing anywhere said a field had been dropped. The onset is\n    already held to this standard: one that is not a number costs the whole TAL and is\n    reported. A duration is one field of an otherwise readable event, so the event is kept —\n    but it is counted, and the run says so.\n  */\n  let duration: number | null = null;\n  let durationUnreadable = false;\n  if (durationText !== null && durationText !== '') {\n    const d = Number(durationText);\n    if (Number.isFinite(d)) duration = d;\n    else durationUnreadable = true;\n  }\n\n  const annotations: Annotation[] = [];\n  for (const raw of parts.slice(1)) {\n    // A trailing separator yields an empty segment; a timekeeping TAL is all empty.\n    if (raw === '') continue;\n    annotations.push({ onset, duration, text: raw, recordIndex });\n  }\n\n  // Per event rather than per TAL: one TAL may carry several texts, and each becomes a row\n  // of annotations.csv with the same empty cell in it.\n  return { onset, annotations, unreadableDurations: durationUnreadable ? annotations.length : 0 };\n}\n\nexport { SEP_TEXT, SEP_DURATION, TAL_END };\n"]}

package/dist/edf/reader.d.ts

@@ -156,6 +156,8 @@ export declare class EdfFile {
         malformed: number;
         /** Unreadable TALs in first position, which carry timing rather than an event. */
         malformedTimekeeping: number;
+        /** Events kept whose stated duration could not be read; see Annotation.duration. */
+        unreadableDurations: number;
     }>;
     close(): Promise<void>;
 }

package/dist/edf/reader.js

@@ -361,9 +361,10 @@ export class EdfFile {
         const recordStarts = new Array(this.recordCount).fill(null);
         let malformed = 0;
         let malformedTimekeeping = 0;
+        let unreadableDurations = 0;
         const channels = this.annotationSignals;
         if (channels.length === 0) {
-            return { annotations, recordStarts, malformed, malformedTimekeeping };
+            return { annotations, recordStarts, malformed, malformedTimekeeping, unreadableDurations };
         }
         const { headerBytes, recordBytes, bytesPerSample } = this.header;
         const buffers = channels.map((c) => Buffer.alloc(c.samplesPerRecord * bytesPerSample));
@@ -386,10 +387,11 @@ export class EdfFile {
                     annotations.push(annotation);
                 malformed += decoded.malformed;
                 malformedTimekeeping += decoded.malformedTimekeeping;
+                unreadableDurations += decoded.unreadableDurations;
             }
         }
         annotations.sort((a, b) => a.onset - b.onset || a.recordIndex - b.recordIndex);
-        return { annotations, recordStarts, malformed, malformedTimekeeping };
+        return { annotations, recordStarts, malformed, malformedTimekeeping, unreadableDurations };
     }
     async close() {
         if (this.#closed)

package/dist/edf/reader.js.map

@@ -1 +1 @@
-{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../src/edf/reader.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Chunked reader for EDF / EDF+ files.\n *\n * Data records are read in batches sized by a byte budget rather than all at once,\n * so peak memory stays flat regardless of how long the recording is. A 4 GB file\n * and a 4 MB file use the same working set.\n */\n\nimport { open, stat } from 'node:fs/promises';\nimport type { FileHandle } from 'node:fs/promises';\n\nimport { createHash } from 'node:crypto';\n\nimport { EdfError } from './errors.js';\nimport type { Diagnostic } from './errors.js';\nimport { FIXED_HEADER_BYTES, SIGNAL_HEADER_BYTES, parseHeader, peekSignalCount } from './header.js';\nimport type { EdfHeader, EdfSignal } from './header.js';\nimport { decodeRecordAnnotations } from './annotations.js';\nimport type { Annotation } from './annotations.js';\nimport { decodeLatin1, readInt16LE } from './bytes.js';\n\n/**\n * How far `readOrigin` looks for a record that states its own start time.\n *\n * Enough that one or two unreadable timekeeping entries at the top of a file cost nothing,\n * few enough that `--info` stays a header read rather than a scan.\n */\nconst RECORDS_SEARCHED_FOR_ORIGIN = 16;\n\n/** Default read budget per batch. Large enough to amortise syscalls, small enough to stay cheap. */\nexport const DEFAULT_CHUNK_BYTES = 8 * 1024 * 1024;\n\nexport interface RecordBatch {\n  /** Index of the first record in this batch, relative to the whole file. */\n  firstRecordIndex: number;\n  recordCount: number;\n  /**\n   * Raw record bytes, `recordCount * header.recordBytes` long.\n   *\n   * The buffer is reused between iterations. Copy anything you need to keep past\n   * the current loop turn.\n   */\n  data: Uint8Array;\n}\n\nexport interface ReadRecordsOptions {\n  /** First record to read, inclusive. Defaults to 0. */\n  startRecord?: number;\n  /** Last record to read, exclusive. Defaults to the file's record count. */\n  endRecord?: number;\n  chunkBytes?: number;\n}\n\nexport class EdfFile {\n  readonly path: string;\n  readonly fileSize: number;\n  /**\n   * Last-modified time when this file was opened, in milliseconds, for the same reason as\n   * `fileSize`.\n   *\n   * Kept as the raw number rather than a Date because `new Date(ms).getTime()` truncates to\n   * whole milliseconds: comparing that against a later `fstat`, which carries the\n   * filesystem's sub-millisecond precision, reported every undisturbed conversion as one\n   * whose input had changed underneath it.\n   */\n  readonly modifiedAtOpenMs: number;\n  readonly header: EdfHeader;\n  /** Records actually present in the file, which may differ from the header's claim. */\n  readonly recordCount: number;\n  readonly trailingBytes: number;\n  readonly diagnostics: Diagnostic[];\n\n  #handle: FileHandle;\n  #closed = false;\n  /** The last answer `changedSinceOpen` computed, so it survives the file being closed. */\n  #changed: boolean | null = null;\n\n  private constructor(init: {\n    path: string;\n    fileSize: number;\n    modifiedAtOpenMs: number;\n    header: EdfHeader;\n    recordCount: number;\n    trailingBytes: number;\n    diagnostics: Diagnostic[];\n    handle: FileHandle;\n  }) {\n    this.path = init.path;\n    this.fileSize = init.fileSize;\n    this.modifiedAtOpenMs = init.modifiedAtOpenMs;\n    this.header = init.header;\n    this.recordCount = init.recordCount;\n    this.trailingBytes = init.trailingBytes;\n    this.diagnostics = init.diagnostics;\n    this.#handle = init.handle;\n  }\n\n  /**\n   * SHA-256 of the bytes this conversion actually read.\n   *\n   * Hashed through the open descriptor, over exactly the `fileSize` bytes that were there\n   * when the file was opened — the same number every record count and window in the output\n   * was derived from. Re-opening the path to hash it afterwards described whatever was at\n   * that name by then: a recording still being written grew from 2,000 records to 3,000\n   * mid-conversion and metadata.json recorded `data_records: 2000` beside the checksum and\n   * byte count of the 3,000-record file, which is provenance for bytes nobody converted.\n   * Replacing the file at that path did the same thing more completely.\n   */\n  async sha256(): Promise<string> {\n    this.#assertOpen();\n    const hash = createHash('sha256');\n    const buffer = Buffer.alloc(Math.min(this.fileSize, 4 * 1024 * 1024) || 1);\n    for (let at = 0; at < this.fileSize; ) {\n      const want = Math.min(buffer.length, this.fileSize - at);\n      const { bytesRead } = await this.#handle.read(buffer, 0, want, at);\n      if (bytesRead <= 0) {\n        throw new EdfError(\n          'UNREADABLE',\n          `Expected ${this.fileSize} bytes to checksum but the file ended at ${at}; ` +\n            `it appears to have changed size while it was being read.`,\n          'Make sure the recording is not still being written to, then try again.',\n        );\n      }\n      hash.update(buffer.subarray(0, bytesRead));\n      at += bytesRead;\n    }\n    return hash.digest('hex');\n  }\n\n  /**\n   * Whether the file has changed since it was opened, by size or by modification time.\n   *\n   * Checked through the descriptor, so it answers for the bytes that were read rather than\n   * for whatever now answers to the same name. A recording still being written is the\n   * ordinary cause, and the conversion is still correct for the data it saw — it is the\n   * claim that the output describes the file as it now stands that stops being true.\n   */\n  async changedSinceOpen(): Promise<boolean> {\n    /*\n      A closed file remembers its last answer rather than inventing a new one.\n\n      Returning false once closed asserted \"it did not change\", which is not something a\n      closed descriptor can know — and `convert()` closes the file before it returns, so\n      `result.file.changedSinceOpen()` denied the very change the INPUT_CHANGED diagnostic\n      in the same result object had just reported. One object, two answers.\n\n      `convert()` always asks before closing, so the cached answer is the true one. A caller\n      who closed the file without ever asking gets an error, which is the same treatment\n      every other method on a closed file gets.\n    */\n    if (this.#closed) {\n      if (this.#changed !== null) return this.#changed;\n      throw new EdfError(\n        'UNREADABLE',\n        `\"${this.path}\" is closed, and whether it changed while it was open was never checked.`,\n        'Ask before closing the file. A ConvertResult carries the answer already, since ' +\n          'convert() checks it on the way out.',\n      );\n    }\n    const now = await this.#handle.stat().catch(() => null);\n    if (now === null) return this.#changed ?? false;\n    this.#changed = now.size !== this.fileSize || now.mtimeMs !== this.modifiedAtOpenMs;\n    return this.#changed;\n  }\n\n  static async open(path: string): Promise<EdfFile> {\n    const info = await stat(path).catch((cause: unknown) => {\n      throw new EdfError('UNREADABLE', `Cannot read \"${path}\": ${describe(cause)}`);\n    });\n    if (info.isDirectory()) {\n      throw new EdfError('UNREADABLE', `\"${path}\" is a directory, not an EDF file.`);\n    }\n    if (!info.isFile()) {\n      throw new EdfError('UNREADABLE', `\"${path}\" is not a regular file.`);\n    }\n\n    const handle = await open(path, 'r');\n    try {\n      const fixed = Buffer.alloc(Math.min(FIXED_HEADER_BYTES, info.size));\n      if (fixed.length > 0) {\n        const bytesRead = await readFully(handle, fixed, 0, fixed.length, 0);\n        if (bytesRead < fixed.length) throw changedWhileReading(0, fixed.length, bytesRead);\n      }\n\n      // The signal count decides how much more header there is to read. Read by the header\n      // parser itself, so the two cannot disagree about which files are readable: this used\n      // to have its own Number(), which tolerated the NUL padding sloppy writers emit but\n      // not the comma decimal separator that COMMA_DECIMAL exists to accept.\n      let headerBuffer = fixed;\n      if (fixed.length === FIXED_HEADER_BYTES) {\n        const ns = peekSignalCount(fixed);\n        if (ns !== null) {\n          const total = FIXED_HEADER_BYTES + ns * SIGNAL_HEADER_BYTES;\n          if (total <= info.size) {\n            headerBuffer = Buffer.alloc(total);\n            const bytesRead = await readFully(handle, headerBuffer, 0, total, 0);\n            if (bytesRead < total) throw changedWhileReading(0, total, bytesRead);\n          }\n        }\n      }\n\n      const { header, recordCount, trailingBytes, diagnostics } = parseHeader(\n        headerBuffer,\n        info.size,\n      );\n\n      return new EdfFile({\n        path,\n        fileSize: info.size,\n        modifiedAtOpenMs: info.mtimeMs,\n        header,\n        recordCount,\n        trailingBytes,\n        diagnostics,\n        handle,\n      });\n    } catch (error) {\n      await handle.close().catch(() => {});\n      throw error;\n    }\n  }\n\n  /** Signal channels, excluding the EDF+ annotations channel. */\n  get dataSignals(): EdfSignal[] {\n    return this.header.signals.filter((s) => !s.isAnnotations);\n  }\n\n  /**\n   * The annotation channel a record's start time is read from.\n   *\n   * EDF+ puts the timekeeping TAL first in the first annotation channel, and this was read as\n   * `annotationSignals[0]` — the first one declared, whether or not it can hold anything. A\n   * writer that declares an annotation channel and gives it zero samples per record leaves a\n   * slot of zero bytes, so nothing was read from it, and the timekeeping in the channel after\n   * it went unread: a three-record EDF+D reported \"3 of 3 data records carry no readable\n   * timekeeping annotation\" about three that were perfectly readable, and timed the file from\n   * zero.\n   *\n   * A channel with no room carries nothing, so it is not the one the TAL is in.\n   */\n  get timekeepingSignal(): EdfSignal | undefined {\n    return this.annotationSignals.find((signal) => signal.samplesPerRecord > 0);\n  }\n\n  get annotationSignals(): EdfSignal[] {\n    return this.header.signals.filter((s) => s.isAnnotations);\n  }\n\n  /** Total recording duration in seconds, based on records actually present. */\n  get durationSeconds(): number {\n    return this.recordCount * this.header.recordDuration;\n  }\n\n  /** Read a half-open range of records in batches. */\n  async *readRecords(options: ReadRecordsOptions = {}): AsyncGenerator<RecordBatch> {\n    this.#assertOpen();\n\n    /*\n      Record bounds have to be whole records.\n\n      A fractional `startRecord` was carried straight into `position = headerBytes +\n      record * recordBytes`, so reading from 1.5 began half a record in and every sample\n      after it was decoded from the wrong offset: on the two-channel test fixture it\n      returned channel 2's values under channel 1's signal, with no error. Clamping\n      silently would be no better, since a caller asking for record 1.5 has a bug the\n      library should name rather than paper over.\n    */\n    for (const [name, value] of [\n      ['startRecord', options.startRecord],\n      ['endRecord', options.endRecord],\n    ] as const) {\n      if (value !== undefined && !Number.isInteger(value)) {\n        throw new EdfError(\n          'BAD_HEADER_FIELD',\n          `readRecords: ${name} must be a whole record index, got ${value}.`,\n          'Record boundaries are the unit the file can be read in; a fractional index would decode samples from the middle of a record.',\n        );\n      }\n    }\n\n    const start = Math.max(0, options.startRecord ?? 0);\n    const end = Math.min(this.recordCount, options.endRecord ?? this.recordCount);\n    if (start >= end) return;\n\n    const { recordBytes } = this.header;\n    /*\n      Checked rather than handed to Buffer.alloc.\n\n      `chunkBytes: NaN` came back as `RangeError: The value of \"size\" is out of range` from\n      inside Node, with no mention of the option that caused it — while a fractional\n      `startRecord` two lines up gets a typed EdfError naming the field. Every other option\n      here is checked; this one reached the allocator.\n    */\n    const budget = options.chunkBytes ?? DEFAULT_CHUNK_BYTES;\n    if (!Number.isFinite(budget) || budget < 1) {\n      throw new EdfError(\n        'UNREADABLE',\n        `chunkBytes must be a positive number of bytes, got ${String(options.chunkBytes)}.`,\n        'It is a ceiling on how much of the file is held at once; one record is read whatever it says.',\n      );\n    }\n    /*\n      The budget is a ceiling, not an amount to reserve.\n\n      `Math.floor(budget / recordBytes)` is how many records would fit in it, and the buffer\n      was that many — whether or not the file had that many. A 848-byte fixture read with a\n      512 MB budget allocated 536,870,880 bytes for its two records, and every ordinary read\n      of a small file reserved the full 8 MB default. Nothing was wrong with the data; the\n      memory just had nothing to do with it.\n\n      Bounded by what is actually going to be read, so a batch of five hundred short\n      recordings costs five hundred short buffers rather than five hundred 8 MB ones.\n    */\n    const perChunk = Math.max(1, Math.min(Math.floor(budget / recordBytes), end - start));\n    const buffer = Buffer.alloc(perChunk * recordBytes);\n\n    for (let record = start; record < end; record += perChunk) {\n      const count = Math.min(perChunk, end - record);\n      const bytes = count * recordBytes;\n      const position = this.header.headerBytes + record * recordBytes;\n\n      const bytesRead = await readFully(this.#handle, buffer, 0, bytes, position);\n      if (bytesRead < bytes) {\n        // The file is shorter than its own size said. Quietly stopping here would\n        // hand back a conversion missing its tail with nothing to show for it.\n        throw new EdfError(\n          'UNREADABLE',\n          `Expected ${bytes} bytes of data at record ${record} but only ${bytesRead} were ` +\n            `available; the file appears to have changed size while it was being read.`,\n          'Make sure the recording is not still being written to, then try again.',\n        );\n      }\n\n      yield { firstRecordIndex: record, recordCount: count, data: buffer.subarray(0, bytes) };\n    }\n  }\n\n  /** Read one sample as its raw digital value. */\n  sampleAt(batch: RecordBatch, recordOffset: number, signal: EdfSignal, sampleIndex: number): number {\n    const position =\n      recordOffset * this.header.recordBytes +\n      signal.byteOffsetInRecord +\n      sampleIndex * this.header.bytesPerSample;\n\n    if (this.header.bytesPerSample === 3) {\n      // BDF stores 24-bit little-endian two's complement. Loading the three bytes\n      // into the top of a 32-bit word and shifting back down sign-extends them.\n      const data = batch.data;\n      return (\n        ((data[position] as number) << 8) |\n        ((data[position + 1] as number) << 16) |\n        ((data[position + 2] as number) << 24)\n      ) >> 8;\n    }\n    return readInt16LE(batch.data, position);\n  }\n\n  /** Byte offset of a signal's samples within a batch. */\n  offsetOf(batch: RecordBatch, recordOffset: number, signal: EdfSignal): number {\n    return recordOffset * this.header.recordBytes + signal.byteOffsetInRecord;\n  }\n\n  /** The annotation channel's raw bytes for one record in a batch. */\n  annotationBytes(batch: RecordBatch, recordOffset: number, signal: EdfSignal): Uint8Array {\n    const start = this.offsetOf(batch, recordOffset, signal);\n    return batch.data.subarray(start, start + signal.samplesPerRecord * this.header.bytesPerSample);\n  }\n\n  /**\n   * Read every EDF+ annotation in the file, plus the start time each record declares.\n   *\n   * Only the annotation channel is read, seeking straight to it inside each record\n   * rather than pulling whole records through memory. On a multi-gigabyte recording\n   * that is the difference between a few kilobytes of I/O and all of it.\n   *\n   * The whole file is always scanned, never just the records inside a requested\n   * window: writers are not obliged to store an annotation in the record its onset\n   * falls in, and some put every annotation in the first record. Reading only the\n   * window's records would drop those entirely.\n   */\n  /**\n   * Where this continuous recording begins, from the first record that says.\n   *\n   * A few records' worth of annotation bytes rather than the whole channel. A continuous\n   * recording's origin is the fraction of a second by which its first record follows the\n   * header's start time, and `--info` needs that to place a requested window — but it does\n   * not need the events, and finding one number by reading every record costs a seek per\n   * record across the whole file, which is the scan `--info` was deliberately spared.\n   *\n   * It reads on past record 0 because a conversion does. This used to stop there, so the\n   * moment one timekeeping TAL was unreadable the two disagreed: the conversion took the\n   * origin from record 1 and timed the file from 0.5s, while `--info` found nothing at\n   * record 0 and reported a recording starting at zero — the same file described two ways by\n   * one tool. Records are contiguous, so record `i` beginning at `t` puts the origin at\n   * `t - i * duration`, and any one of them settles it.\n   *\n   * The bound is what keeps this cheap: a file whose first `RECORDS_SEARCHED_FOR_ORIGIN`\n   * timekeeping entries are all unreadable reports an origin of zero here, and converting it\n   * raises ANNOTATION_DECODE_FAILED for every one of them.\n   *\n   * Returns null when there is nothing to read it from, in which case the origin is zero.\n   */\n  async readOrigin(): Promise<number | null> {\n    return (await this.scanOrigin()).origin;\n  }\n\n  /**\n   * The origin, and what the search saw on the way to it.\n   *\n   * `--info` takes this route for a continuous recording rather than reading every record,\n   * and reported nothing when the timekeeping it read was unreadable: the count was hard-coded\n   * to zero at the call site, so a file whose first TAL cannot be parsed raised\n   * ANNOTATION_DECODE_FAILED when converted and nothing under `--info`. Its byte-identical\n   * EDF+D twin — same bytes but for the reserved field, which has nothing to do with the\n   * defect — raised it both ways, because that path reads every record and counts as it goes.\n   *\n   * The failure was being read and then thrown away. `readOrigin` keeps its shape for callers\n   * who only want the number.\n   */\n  async scanOrigin(): Promise<{ origin: number | null; malformedTimekeeping: number }> {\n    this.#assertOpen();\n\n    let malformedTimekeeping = 0;\n    const channel = this.timekeepingSignal;\n    if (!channel || this.recordCount === 0) return { origin: null, malformedTimekeeping };\n\n    const { headerBytes, bytesPerSample, recordBytes, recordDuration } = this.header;\n    const buffer = Buffer.alloc(channel.samplesPerRecord * bytesPerSample);\n    if (buffer.length === 0) return { origin: null, malformedTimekeeping };\n\n    const searched = Math.min(this.recordCount, RECORDS_SEARCHED_FOR_ORIGIN);\n    for (let record = 0; record < searched; record++) {\n      const offset = headerBytes + record * recordBytes + channel.byteOffsetInRecord;\n      const bytesRead = await readFully(this.#handle, buffer, 0, buffer.length, offset);\n      if (bytesRead < buffer.length) return { origin: null, malformedTimekeeping };\n\n      const decoded = decodeRecordAnnotations(buffer, record);\n      malformedTimekeeping += decoded.malformedTimekeeping;\n      if (decoded.recordStart !== null) {\n        return { origin: decoded.recordStart - record * recordDuration, malformedTimekeeping };\n      }\n    }\n    return { origin: null, malformedTimekeeping };\n  }\n\n  async readAnnotations(): Promise<{\n    annotations: Annotation[];\n    recordStarts: (number | null)[];\n    malformed: number;\n    /** Unreadable TALs in first position, which carry timing rather than an event. */\n    malformedTimekeeping: number;\n  }> {\n    this.#assertOpen();\n\n    const annotations: Annotation[] = [];\n    const recordStarts: (number | null)[] = new Array<number | null>(this.recordCount).fill(null);\n    let malformed = 0;\n    let malformedTimekeeping = 0;\n\n    const channels = this.annotationSignals;\n    if (channels.length === 0) {\n      return { annotations, recordStarts, malformed, malformedTimekeeping };\n    }\n\n    const { headerBytes, recordBytes, bytesPerSample } = this.header;\n    const buffers = channels.map((c) => Buffer.alloc(c.samplesPerRecord * bytesPerSample));\n    const timekeeping = this.timekeepingSignal;\n\n    for (let record = 0; record < this.recordCount; record++) {\n      for (const [position, channel] of channels.entries()) {\n        const buffer = buffers[position];\n        if (!buffer || buffer.length === 0) continue;\n\n        const offset = headerBytes + record * recordBytes + channel.byteOffsetInRecord;\n        const bytesRead = await readFully(this.#handle, buffer, 0, buffer.length, offset);\n        if (bytesRead < buffer.length) {\n          throw changedWhileReading(record, buffer.length, bytesRead, 'annotation data');\n        }\n\n        // Only the timekeeping channel carries the record's start; see timekeepingSignal.\n        const decoded = decodeRecordAnnotations(buffer, record, channel === timekeeping);\n        if (channel === timekeeping) recordStarts[record] = decoded.recordStart;\n        for (const annotation of decoded.annotations) annotations.push(annotation);\n        malformed += decoded.malformed;\n        malformedTimekeeping += decoded.malformedTimekeeping;\n      }\n    }\n\n    annotations.sort((a, b) => a.onset - b.onset || a.recordIndex - b.recordIndex);\n    return { annotations, recordStarts, malformed, malformedTimekeeping };\n  }\n\n  async close(): Promise<void> {\n    if (this.#closed) return;\n    this.#closed = true;\n    await this.#handle.close();\n  }\n\n  #assertOpen(): void {\n    if (this.#closed) throw new EdfError('UNREADABLE', 'This EDF file has already been closed.');\n  }\n}\n\nfunction describe(cause: unknown): string {\n  if (cause instanceof Error) {\n    const code = (cause as NodeJS.ErrnoException).code;\n    if (code === 'ENOENT') return 'no such file';\n    if (code === 'EACCES') return 'permission denied';\n    return cause.message;\n  }\n  return String(cause);\n}\n\n/**\n * The most `fs.read` will accept as a length.\n *\n * Node asserts on a length that does not fit in a signed 32-bit integer, and it asserts in\n * C++: `Assertion failed: args[3]->IsInt32()`, forty frames of native stack, SIGABRT. Not an\n * exception — nothing in JavaScript sees it, so no catch block and no `uncaughtException`\n * handler runs, and a library consumer's whole process goes down with it.\n *\n * A round gigabyte rather than the exact limit, so the loop below does whole even reads.\n */\nconst MAX_READ_BYTES = 1024 * 1024 * 1024;\n\n/** Fill a requested region unless EOF is reached; regular-file reads may legally be short. */\nasync function readFully(\n  handle: FileHandle,\n  buffer: Buffer,\n  offset: number,\n  length: number,\n  position: number,\n): Promise<number> {\n  let total = 0;\n  while (total < length) {\n    /*\n      Capped, because one data record can be larger than a single read may be.\n\n      A record is read in one call when it exceeds the chunk budget — there is nothing\n      smaller to divide it by, since a record is the unit the format is addressed in. EDF's\n      samples-per-record field is 8 characters, so eleven channels at 99,999,999 samples make\n      a record of 2.2 GB, and a long record duration at ordinary rates gets there too. That\n      went to `fs.read` as a single length over 2^31-1 and took the process out with a native\n      assertion rather than an error.\n\n      Looping was already how a short read is handled, so the cap costs one more iteration\n      per gigabyte and nothing else.\n    */\n    const want = Math.min(length - total, MAX_READ_BYTES);\n    const { bytesRead } = await handle.read(buffer, offset + total, want, position + total);\n    if (bytesRead === 0) break;\n    total += bytesRead;\n  }\n  return total;\n}\n\nfunction changedWhileReading(\n  record: number,\n  expected: number,\n  actual: number,\n  subject = 'data',\n): EdfError {\n  return new EdfError(\n    'UNREADABLE',\n    `Expected ${expected} bytes of ${subject} at record ${record} but only ${actual} were ` +\n      `available; the file appears to have changed size while it was being read.`,\n    'Make sure the recording is not still being written to, then try again.',\n  );\n}\n"]}
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../src/edf/reader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEpG,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAEvC,oGAAoG;AACpG,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAuBnD,MAAM,OAAO,OAAO;IACT,IAAI,CAAS;IACb,QAAQ,CAAS;IAC1B;;;;;;;;OAQG;IACM,gBAAgB,CAAS;IACzB,MAAM,CAAY;IAC3B,sFAAsF;IAC7E,WAAW,CAAS;IACpB,aAAa,CAAS;IACtB,WAAW,CAAe;IAEnC,OAAO,CAAa;IACpB,OAAO,GAAG,KAAK,CAAC;IAChB,yFAAyF;IACzF,QAAQ,GAAmB,IAAI,CAAC;IAEhC,YAAoB,IASnB;QACC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM;QACV,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3E,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,QAAQ,GAAI,CAAC;YACtC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC,CAAC;YACzD,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;YACnE,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;gBACnB,MAAM,IAAI,QAAQ,CAChB,YAAY,EACZ,YAAY,IAAI,CAAC,QAAQ,4CAA4C,EAAE,IAAI;oBACzE,0DAA0D,EAC5D,wEAAwE,CACzE,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;YAC3C,EAAE,IAAI,SAAS,CAAC;QAClB,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,gBAAgB;QACpB;;;;;;;;;;;UAWE;QACF,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;YACjD,MAAM,IAAI,QAAQ,CAChB,YAAY,EACZ,IAAI,IAAI,CAAC,IAAI,0EAA0E,EACvF,iFAAiF;gBAC/E,qCAAqC,CACxC,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QACxD,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;QAChD,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC,gBAAgB,CAAC;QACpF,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAY;QAC5B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACrD,MAAM,IAAI,QAAQ,CAAC,YAAY,EAAE,gBAAgB,IAAI,MAAM,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChF,CAAC,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACvB,MAAM,IAAI,QAAQ,CAAC,YAAY,EAAE,IAAI,IAAI,oCAAoC,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACnB,MAAM,IAAI,QAAQ,CAAC,YAAY,EAAE,IAAI,IAAI,0BAA0B,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YACpE,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;gBACrE,IAAI,SAAS,GAAG,KAAK,CAAC,MAAM;oBAAE,MAAM,mBAAmB,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACtF,CAAC;YAED,qFAAqF;YACrF,sFAAsF;YACtF,oFAAoF;YACpF,uEAAuE;YACvE,IAAI,YAAY,GAAG,KAAK,CAAC;YACzB,IAAI,KAAK,CAAC,MAAM,KAAK,kBAAkB,EAAE,CAAC;gBACxC,MAAM,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;gBAClC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;oBAChB,MAAM,KAAK,GAAG,kBAAkB,GAAG,EAAE,GAAG,mBAAmB,CAAC;oBAC5D,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;wBACvB,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;wBACnC,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;wBACrE,IAAI,SAAS,GAAG,KAAK;4BAAE,MAAM,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;oBACxE,CAAC;gBACH,CAAC;YACH,CAAC;YAED,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,GAAG,WAAW,CACrE,YAAY,EACZ,IAAI,CAAC,IAAI,CACV,CAAC;YAEF,OAAO,IAAI,OAAO,CAAC;gBACjB,IAAI;gBACJ,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,gBAAgB,EAAE,IAAI,CAAC,OAAO;gBAC9B,MAAM;gBACN,WAAW;gBACX,aAAa;gBACb,WAAW;gBACX,MAAM;aACP,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACrC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,+DAA+D;IAC/D,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,IAAI,iBAAiB;QACnB,OAAO,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,iBAAiB;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAC5D,CAAC;IAED,8EAA8E;IAC9E,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;IACvD,CAAC;IAED,oDAAoD;IACpD,KAAK,CAAC,CAAC,WAAW,CAAC,UAA8B,EAAE;QACjD,IAAI,CAAC,WAAW,EAAE,CAAC;QAEnB;;;;;;;;;UASE;QACF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI;YAC1B,CAAC,aAAa,EAAE,OAAO,CAAC,WAAW,CAAC;YACpC,CAAC,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC;SACxB,EAAE,CAAC;YACX,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpD,MAAM,IAAI,QAAQ,CAChB,kBAAkB,EAClB,gBAAgB,IAAI,sCAAsC,KAAK,GAAG,EAClE,8HAA8H,CAC/H,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC;QAC9E,IAAI,KAAK,IAAI,GAAG;YAAE,OAAO;QAEzB,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACpC;;;;;;;UAOE;QACF,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;QACzD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,QAAQ,CAChB,YAAY,EACZ,sDAAsD,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,EACnF,+FAA+F,CAChG,CAAC;QACJ,CAAC;QACD;;;;;;;;;;;UAWE;QACF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC;QACtF,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,WAAW,CAAC,CAAC;QAEpD,KAAK,IAAI,MAAM,GAAG,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,GAAG,MAAM,CAAC,CAAC;YAC/C,MAAM,KAAK,GAAG,KAAK,GAAG,WAAW,CAAC;YAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,GAAG,MAAM,GAAG,WAAW,CAAC;YAEhE,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;YAC5E,IAAI,SAAS,GAAG,KAAK,EAAE,CAAC;gBACtB,0EAA0E;gBAC1E,uEAAuE;gBACvE,MAAM,IAAI,QAAQ,CAChB,YAAY,EACZ,YAAY,KAAK,4BAA4B,MAAM,aAAa,SAAS,QAAQ;oBAC/E,2EAA2E,EAC7E,wEAAwE,CACzE,CAAC;YACJ,CAAC;YAED,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;QAC1F,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,QAAQ,CAAC,KAAkB,EAAE,YAAoB,EAAE,MAAiB,EAAE,WAAmB;QACvF,MAAM,QAAQ,GACZ,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW;YACtC,MAAM,CAAC,kBAAkB;YACzB,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;QAE3C,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC;YACrC,4EAA4E;YAC5E,0EAA0E;YAC1E,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YACxB,OAAO,CACL,CAAE,IAAI,CAAC,QAAQ,CAAY,IAAI,CAAC,CAAC;gBACjC,CAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAY,IAAI,EAAE,CAAC;gBACtC,CAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAY,IAAI,EAAE,CAAC,CACvC,IAAI,CAAC,CAAC;QACT,CAAC;QACD,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,wDAAwD;IACxD,QAAQ,CAAC,KAAkB,EAAE,YAAoB,EAAE,MAAiB;QAClE,OAAO,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,GAAG,MAAM,CAAC,kBAAkB,CAAC;IAC5E,CAAC;IAED,oEAAoE;IACpE,eAAe,CAAC,KAAkB,EAAE,YAAoB,EAAE,MAAiB;QACzE,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;QACzD,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAClG,CAAC;IAED;;;;;;;;;;;OAWG;IACH;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,UAAU;QACd,OAAO,CAAC,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,WAAW,EAAE,CAAC;QAEnB,IAAI,oBAAoB,GAAG,CAAC,CAAC;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,iBAAiB,CAAC;QACvC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,WAAW,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QAEtF,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACjF,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,GAAG,cAAc,CAAC,CAAC;QACvE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QAEvE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,2BAA2B,CAAC,CAAC;QACzE,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;YACjD,MAAM,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;YAC/E,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAClF,IAAI,SAAS,GAAG,MAAM,CAAC,MAAM;gBAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;YAE7E,MAAM,OAAO,GAAG,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACxD,oBAAoB,IAAI,OAAO,CAAC,oBAAoB,CAAC;YACrD,IAAI,OAAO,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,WAAW,GAAG,MAAM,GAAG,cAAc,EAAE,oBAAoB,EAAE,CAAC;YACzF,CAAC;QACH,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,eAAe;QASnB,IAAI,CAAC,WAAW,EAAE,CAAC;QAEnB,MAAM,WAAW,GAAiB,EAAE,CAAC;QACrC,MAAM,YAAY,GAAsB,IAAI,KAAK,CAAgB,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9F,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,IAAI,oBAAoB,GAAG,CAAC,CAAC;QAC7B,IAAI,mBAAmB,GAAG,CAAC,CAAC;QAE5B,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC;QACxC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;QAC7F,CAAC;QAED,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACjE,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,GAAG,cAAc,CAAC,CAAC,CAAC;QACvF,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAE3C,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC;YACzD,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;gBACrD,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACjC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;oBAAE,SAAS;gBAE7C,MAAM,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;gBAC/E,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAClF,IAAI,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;oBAC9B,MAAM,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,iBAAiB,CAAC,CAAC;gBACjF,CAAC;gBAED,kFAAkF;gBAClF,MAAM,OAAO,GAAG,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,WAAW,CAAC,CAAC;gBACjF,IAAI,OAAO,KAAK,WAAW;oBAAE,YAAY,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;gBACxE,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,WAAW;oBAAE,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBAC3E,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC;gBAC/B,oBAAoB,IAAI,OAAO,CAAC,oBAAoB,CAAC;gBACrD,mBAAmB,IAAI,OAAO,CAAC,mBAAmB,CAAC;YACrD,CAAC;QACH,CAAC;QAED,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;QAC/E,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;IAC7F,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;IAED,WAAW;QACT,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,QAAQ,CAAC,YAAY,EAAE,wCAAwC,CAAC,CAAC;IAC/F,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;QACnD,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,cAAc,CAAC;QAC7C,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,mBAAmB,CAAC;QAClD,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE1C,8FAA8F;AAC9F,KAAK,UAAU,SAAS,CACtB,MAAkB,EAClB,MAAc,EACd,MAAc,EACd,MAAc,EACd,QAAgB;IAEhB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,MAAM,EAAE,CAAC;QACtB;;;;;;;;;;;;UAYE;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,KAAK,EAAE,cAAc,CAAC,CAAC;QACtD,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;QACxF,IAAI,SAAS,KAAK,CAAC;YAAE,MAAM;QAC3B,KAAK,IAAI,SAAS,CAAC;IACrB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,mBAAmB,CAC1B,MAAc,EACd,QAAgB,EAChB,MAAc,EACd,OAAO,GAAG,MAAM;IAEhB,OAAO,IAAI,QAAQ,CACjB,YAAY,EACZ,YAAY,QAAQ,aAAa,OAAO,cAAc,MAAM,aAAa,MAAM,QAAQ;QACrF,2EAA2E,EAC7E,wEAAwE,CACzE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Chunked reader for EDF / EDF+ files.\n *\n * Data records are read in batches sized by a byte budget rather than all at once,\n * so peak memory stays flat regardless of how long the recording is. A 4 GB file\n * and a 4 MB file use the same working set.\n */\n\nimport { open, stat } from 'node:fs/promises';\nimport type { FileHandle } from 'node:fs/promises';\n\nimport { createHash } from 'node:crypto';\n\nimport { EdfError } from './errors.js';\nimport type { Diagnostic } from './errors.js';\nimport { FIXED_HEADER_BYTES, SIGNAL_HEADER_BYTES, parseHeader, peekSignalCount } from './header.js';\nimport type { EdfHeader, EdfSignal } from './header.js';\nimport { decodeRecordAnnotations } from './annotations.js';\nimport type { Annotation } from './annotations.js';\nimport { decodeLatin1, readInt16LE } from './bytes.js';\n\n/**\n * How far `readOrigin` looks for a record that states its own start time.\n *\n * Enough that one or two unreadable timekeeping entries at the top of a file cost nothing,\n * few enough that `--info` stays a header read rather than a scan.\n */\nconst RECORDS_SEARCHED_FOR_ORIGIN = 16;\n\n/** Default read budget per batch. Large enough to amortise syscalls, small enough to stay cheap. */\nexport const DEFAULT_CHUNK_BYTES = 8 * 1024 * 1024;\n\nexport interface RecordBatch {\n  /** Index of the first record in this batch, relative to the whole file. */\n  firstRecordIndex: number;\n  recordCount: number;\n  /**\n   * Raw record bytes, `recordCount * header.recordBytes` long.\n   *\n   * The buffer is reused between iterations. Copy anything you need to keep past\n   * the current loop turn.\n   */\n  data: Uint8Array;\n}\n\nexport interface ReadRecordsOptions {\n  /** First record to read, inclusive. Defaults to 0. */\n  startRecord?: number;\n  /** Last record to read, exclusive. Defaults to the file's record count. */\n  endRecord?: number;\n  chunkBytes?: number;\n}\n\nexport class EdfFile {\n  readonly path: string;\n  readonly fileSize: number;\n  /**\n   * Last-modified time when this file was opened, in milliseconds, for the same reason as\n   * `fileSize`.\n   *\n   * Kept as the raw number rather than a Date because `new Date(ms).getTime()` truncates to\n   * whole milliseconds: comparing that against a later `fstat`, which carries the\n   * filesystem's sub-millisecond precision, reported every undisturbed conversion as one\n   * whose input had changed underneath it.\n   */\n  readonly modifiedAtOpenMs: number;\n  readonly header: EdfHeader;\n  /** Records actually present in the file, which may differ from the header's claim. */\n  readonly recordCount: number;\n  readonly trailingBytes: number;\n  readonly diagnostics: Diagnostic[];\n\n  #handle: FileHandle;\n  #closed = false;\n  /** The last answer `changedSinceOpen` computed, so it survives the file being closed. */\n  #changed: boolean | null = null;\n\n  private constructor(init: {\n    path: string;\n    fileSize: number;\n    modifiedAtOpenMs: number;\n    header: EdfHeader;\n    recordCount: number;\n    trailingBytes: number;\n    diagnostics: Diagnostic[];\n    handle: FileHandle;\n  }) {\n    this.path = init.path;\n    this.fileSize = init.fileSize;\n    this.modifiedAtOpenMs = init.modifiedAtOpenMs;\n    this.header = init.header;\n    this.recordCount = init.recordCount;\n    this.trailingBytes = init.trailingBytes;\n    this.diagnostics = init.diagnostics;\n    this.#handle = init.handle;\n  }\n\n  /**\n   * SHA-256 of the bytes this conversion actually read.\n   *\n   * Hashed through the open descriptor, over exactly the `fileSize` bytes that were there\n   * when the file was opened — the same number every record count and window in the output\n   * was derived from. Re-opening the path to hash it afterwards described whatever was at\n   * that name by then: a recording still being written grew from 2,000 records to 3,000\n   * mid-conversion and metadata.json recorded `data_records: 2000` beside the checksum and\n   * byte count of the 3,000-record file, which is provenance for bytes nobody converted.\n   * Replacing the file at that path did the same thing more completely.\n   */\n  async sha256(): Promise<string> {\n    this.#assertOpen();\n    const hash = createHash('sha256');\n    const buffer = Buffer.alloc(Math.min(this.fileSize, 4 * 1024 * 1024) || 1);\n    for (let at = 0; at < this.fileSize; ) {\n      const want = Math.min(buffer.length, this.fileSize - at);\n      const { bytesRead } = await this.#handle.read(buffer, 0, want, at);\n      if (bytesRead <= 0) {\n        throw new EdfError(\n          'UNREADABLE',\n          `Expected ${this.fileSize} bytes to checksum but the file ended at ${at}; ` +\n            `it appears to have changed size while it was being read.`,\n          'Make sure the recording is not still being written to, then try again.',\n        );\n      }\n      hash.update(buffer.subarray(0, bytesRead));\n      at += bytesRead;\n    }\n    return hash.digest('hex');\n  }\n\n  /**\n   * Whether the file has changed since it was opened, by size or by modification time.\n   *\n   * Checked through the descriptor, so it answers for the bytes that were read rather than\n   * for whatever now answers to the same name. A recording still being written is the\n   * ordinary cause, and the conversion is still correct for the data it saw — it is the\n   * claim that the output describes the file as it now stands that stops being true.\n   */\n  async changedSinceOpen(): Promise<boolean> {\n    /*\n      A closed file remembers its last answer rather than inventing a new one.\n\n      Returning false once closed asserted \"it did not change\", which is not something a\n      closed descriptor can know — and `convert()` closes the file before it returns, so\n      `result.file.changedSinceOpen()` denied the very change the INPUT_CHANGED diagnostic\n      in the same result object had just reported. One object, two answers.\n\n      `convert()` always asks before closing, so the cached answer is the true one. A caller\n      who closed the file without ever asking gets an error, which is the same treatment\n      every other method on a closed file gets.\n    */\n    if (this.#closed) {\n      if (this.#changed !== null) return this.#changed;\n      throw new EdfError(\n        'UNREADABLE',\n        `\"${this.path}\" is closed, and whether it changed while it was open was never checked.`,\n        'Ask before closing the file. A ConvertResult carries the answer already, since ' +\n          'convert() checks it on the way out.',\n      );\n    }\n    const now = await this.#handle.stat().catch(() => null);\n    if (now === null) return this.#changed ?? false;\n    this.#changed = now.size !== this.fileSize || now.mtimeMs !== this.modifiedAtOpenMs;\n    return this.#changed;\n  }\n\n  static async open(path: string): Promise<EdfFile> {\n    const info = await stat(path).catch((cause: unknown) => {\n      throw new EdfError('UNREADABLE', `Cannot read \"${path}\": ${describe(cause)}`);\n    });\n    if (info.isDirectory()) {\n      throw new EdfError('UNREADABLE', `\"${path}\" is a directory, not an EDF file.`);\n    }\n    if (!info.isFile()) {\n      throw new EdfError('UNREADABLE', `\"${path}\" is not a regular file.`);\n    }\n\n    const handle = await open(path, 'r');\n    try {\n      const fixed = Buffer.alloc(Math.min(FIXED_HEADER_BYTES, info.size));\n      if (fixed.length > 0) {\n        const bytesRead = await readFully(handle, fixed, 0, fixed.length, 0);\n        if (bytesRead < fixed.length) throw changedWhileReading(0, fixed.length, bytesRead);\n      }\n\n      // The signal count decides how much more header there is to read. Read by the header\n      // parser itself, so the two cannot disagree about which files are readable: this used\n      // to have its own Number(), which tolerated the NUL padding sloppy writers emit but\n      // not the comma decimal separator that COMMA_DECIMAL exists to accept.\n      let headerBuffer = fixed;\n      if (fixed.length === FIXED_HEADER_BYTES) {\n        const ns = peekSignalCount(fixed);\n        if (ns !== null) {\n          const total = FIXED_HEADER_BYTES + ns * SIGNAL_HEADER_BYTES;\n          if (total <= info.size) {\n            headerBuffer = Buffer.alloc(total);\n            const bytesRead = await readFully(handle, headerBuffer, 0, total, 0);\n            if (bytesRead < total) throw changedWhileReading(0, total, bytesRead);\n          }\n        }\n      }\n\n      const { header, recordCount, trailingBytes, diagnostics } = parseHeader(\n        headerBuffer,\n        info.size,\n      );\n\n      return new EdfFile({\n        path,\n        fileSize: info.size,\n        modifiedAtOpenMs: info.mtimeMs,\n        header,\n        recordCount,\n        trailingBytes,\n        diagnostics,\n        handle,\n      });\n    } catch (error) {\n      await handle.close().catch(() => {});\n      throw error;\n    }\n  }\n\n  /** Signal channels, excluding the EDF+ annotations channel. */\n  get dataSignals(): EdfSignal[] {\n    return this.header.signals.filter((s) => !s.isAnnotations);\n  }\n\n  /**\n   * The annotation channel a record's start time is read from.\n   *\n   * EDF+ puts the timekeeping TAL first in the first annotation channel, and this was read as\n   * `annotationSignals[0]` — the first one declared, whether or not it can hold anything. A\n   * writer that declares an annotation channel and gives it zero samples per record leaves a\n   * slot of zero bytes, so nothing was read from it, and the timekeeping in the channel after\n   * it went unread: a three-record EDF+D reported \"3 of 3 data records carry no readable\n   * timekeeping annotation\" about three that were perfectly readable, and timed the file from\n   * zero.\n   *\n   * A channel with no room carries nothing, so it is not the one the TAL is in.\n   */\n  get timekeepingSignal(): EdfSignal | undefined {\n    return this.annotationSignals.find((signal) => signal.samplesPerRecord > 0);\n  }\n\n  get annotationSignals(): EdfSignal[] {\n    return this.header.signals.filter((s) => s.isAnnotations);\n  }\n\n  /** Total recording duration in seconds, based on records actually present. */\n  get durationSeconds(): number {\n    return this.recordCount * this.header.recordDuration;\n  }\n\n  /** Read a half-open range of records in batches. */\n  async *readRecords(options: ReadRecordsOptions = {}): AsyncGenerator<RecordBatch> {\n    this.#assertOpen();\n\n    /*\n      Record bounds have to be whole records.\n\n      A fractional `startRecord` was carried straight into `position = headerBytes +\n      record * recordBytes`, so reading from 1.5 began half a record in and every sample\n      after it was decoded from the wrong offset: on the two-channel test fixture it\n      returned channel 2's values under channel 1's signal, with no error. Clamping\n      silently would be no better, since a caller asking for record 1.5 has a bug the\n      library should name rather than paper over.\n    */\n    for (const [name, value] of [\n      ['startRecord', options.startRecord],\n      ['endRecord', options.endRecord],\n    ] as const) {\n      if (value !== undefined && !Number.isInteger(value)) {\n        throw new EdfError(\n          'BAD_HEADER_FIELD',\n          `readRecords: ${name} must be a whole record index, got ${value}.`,\n          'Record boundaries are the unit the file can be read in; a fractional index would decode samples from the middle of a record.',\n        );\n      }\n    }\n\n    const start = Math.max(0, options.startRecord ?? 0);\n    const end = Math.min(this.recordCount, options.endRecord ?? this.recordCount);\n    if (start >= end) return;\n\n    const { recordBytes } = this.header;\n    /*\n      Checked rather than handed to Buffer.alloc.\n\n      `chunkBytes: NaN` came back as `RangeError: The value of \"size\" is out of range` from\n      inside Node, with no mention of the option that caused it — while a fractional\n      `startRecord` two lines up gets a typed EdfError naming the field. Every other option\n      here is checked; this one reached the allocator.\n    */\n    const budget = options.chunkBytes ?? DEFAULT_CHUNK_BYTES;\n    if (!Number.isFinite(budget) || budget < 1) {\n      throw new EdfError(\n        'UNREADABLE',\n        `chunkBytes must be a positive number of bytes, got ${String(options.chunkBytes)}.`,\n        'It is a ceiling on how much of the file is held at once; one record is read whatever it says.',\n      );\n    }\n    /*\n      The budget is a ceiling, not an amount to reserve.\n\n      `Math.floor(budget / recordBytes)` is how many records would fit in it, and the buffer\n      was that many — whether or not the file had that many. A 848-byte fixture read with a\n      512 MB budget allocated 536,870,880 bytes for its two records, and every ordinary read\n      of a small file reserved the full 8 MB default. Nothing was wrong with the data; the\n      memory just had nothing to do with it.\n\n      Bounded by what is actually going to be read, so a batch of five hundred short\n      recordings costs five hundred short buffers rather than five hundred 8 MB ones.\n    */\n    const perChunk = Math.max(1, Math.min(Math.floor(budget / recordBytes), end - start));\n    const buffer = Buffer.alloc(perChunk * recordBytes);\n\n    for (let record = start; record < end; record += perChunk) {\n      const count = Math.min(perChunk, end - record);\n      const bytes = count * recordBytes;\n      const position = this.header.headerBytes + record * recordBytes;\n\n      const bytesRead = await readFully(this.#handle, buffer, 0, bytes, position);\n      if (bytesRead < bytes) {\n        // The file is shorter than its own size said. Quietly stopping here would\n        // hand back a conversion missing its tail with nothing to show for it.\n        throw new EdfError(\n          'UNREADABLE',\n          `Expected ${bytes} bytes of data at record ${record} but only ${bytesRead} were ` +\n            `available; the file appears to have changed size while it was being read.`,\n          'Make sure the recording is not still being written to, then try again.',\n        );\n      }\n\n      yield { firstRecordIndex: record, recordCount: count, data: buffer.subarray(0, bytes) };\n    }\n  }\n\n  /** Read one sample as its raw digital value. */\n  sampleAt(batch: RecordBatch, recordOffset: number, signal: EdfSignal, sampleIndex: number): number {\n    const position =\n      recordOffset * this.header.recordBytes +\n      signal.byteOffsetInRecord +\n      sampleIndex * this.header.bytesPerSample;\n\n    if (this.header.bytesPerSample === 3) {\n      // BDF stores 24-bit little-endian two's complement. Loading the three bytes\n      // into the top of a 32-bit word and shifting back down sign-extends them.\n      const data = batch.data;\n      return (\n        ((data[position] as number) << 8) |\n        ((data[position + 1] as number) << 16) |\n        ((data[position + 2] as number) << 24)\n      ) >> 8;\n    }\n    return readInt16LE(batch.data, position);\n  }\n\n  /** Byte offset of a signal's samples within a batch. */\n  offsetOf(batch: RecordBatch, recordOffset: number, signal: EdfSignal): number {\n    return recordOffset * this.header.recordBytes + signal.byteOffsetInRecord;\n  }\n\n  /** The annotation channel's raw bytes for one record in a batch. */\n  annotationBytes(batch: RecordBatch, recordOffset: number, signal: EdfSignal): Uint8Array {\n    const start = this.offsetOf(batch, recordOffset, signal);\n    return batch.data.subarray(start, start + signal.samplesPerRecord * this.header.bytesPerSample);\n  }\n\n  /**\n   * Read every EDF+ annotation in the file, plus the start time each record declares.\n   *\n   * Only the annotation channel is read, seeking straight to it inside each record\n   * rather than pulling whole records through memory. On a multi-gigabyte recording\n   * that is the difference between a few kilobytes of I/O and all of it.\n   *\n   * The whole file is always scanned, never just the records inside a requested\n   * window: writers are not obliged to store an annotation in the record its onset\n   * falls in, and some put every annotation in the first record. Reading only the\n   * window's records would drop those entirely.\n   */\n  /**\n   * Where this continuous recording begins, from the first record that says.\n   *\n   * A few records' worth of annotation bytes rather than the whole channel. A continuous\n   * recording's origin is the fraction of a second by which its first record follows the\n   * header's start time, and `--info` needs that to place a requested window — but it does\n   * not need the events, and finding one number by reading every record costs a seek per\n   * record across the whole file, which is the scan `--info` was deliberately spared.\n   *\n   * It reads on past record 0 because a conversion does. This used to stop there, so the\n   * moment one timekeeping TAL was unreadable the two disagreed: the conversion took the\n   * origin from record 1 and timed the file from 0.5s, while `--info` found nothing at\n   * record 0 and reported a recording starting at zero — the same file described two ways by\n   * one tool. Records are contiguous, so record `i` beginning at `t` puts the origin at\n   * `t - i * duration`, and any one of them settles it.\n   *\n   * The bound is what keeps this cheap: a file whose first `RECORDS_SEARCHED_FOR_ORIGIN`\n   * timekeeping entries are all unreadable reports an origin of zero here, and converting it\n   * raises ANNOTATION_DECODE_FAILED for every one of them.\n   *\n   * Returns null when there is nothing to read it from, in which case the origin is zero.\n   */\n  async readOrigin(): Promise<number | null> {\n    return (await this.scanOrigin()).origin;\n  }\n\n  /**\n   * The origin, and what the search saw on the way to it.\n   *\n   * `--info` takes this route for a continuous recording rather than reading every record,\n   * and reported nothing when the timekeeping it read was unreadable: the count was hard-coded\n   * to zero at the call site, so a file whose first TAL cannot be parsed raised\n   * ANNOTATION_DECODE_FAILED when converted and nothing under `--info`. Its byte-identical\n   * EDF+D twin — same bytes but for the reserved field, which has nothing to do with the\n   * defect — raised it both ways, because that path reads every record and counts as it goes.\n   *\n   * The failure was being read and then thrown away. `readOrigin` keeps its shape for callers\n   * who only want the number.\n   */\n  async scanOrigin(): Promise<{ origin: number | null; malformedTimekeeping: number }> {\n    this.#assertOpen();\n\n    let malformedTimekeeping = 0;\n    const channel = this.timekeepingSignal;\n    if (!channel || this.recordCount === 0) return { origin: null, malformedTimekeeping };\n\n    const { headerBytes, bytesPerSample, recordBytes, recordDuration } = this.header;\n    const buffer = Buffer.alloc(channel.samplesPerRecord * bytesPerSample);\n    if (buffer.length === 0) return { origin: null, malformedTimekeeping };\n\n    const searched = Math.min(this.recordCount, RECORDS_SEARCHED_FOR_ORIGIN);\n    for (let record = 0; record < searched; record++) {\n      const offset = headerBytes + record * recordBytes + channel.byteOffsetInRecord;\n      const bytesRead = await readFully(this.#handle, buffer, 0, buffer.length, offset);\n      if (bytesRead < buffer.length) return { origin: null, malformedTimekeeping };\n\n      const decoded = decodeRecordAnnotations(buffer, record);\n      malformedTimekeeping += decoded.malformedTimekeeping;\n      if (decoded.recordStart !== null) {\n        return { origin: decoded.recordStart - record * recordDuration, malformedTimekeeping };\n      }\n    }\n    return { origin: null, malformedTimekeeping };\n  }\n\n  async readAnnotations(): Promise<{\n    annotations: Annotation[];\n    recordStarts: (number | null)[];\n    malformed: number;\n    /** Unreadable TALs in first position, which carry timing rather than an event. */\n    malformedTimekeeping: number;\n    /** Events kept whose stated duration could not be read; see Annotation.duration. */\n    unreadableDurations: number;\n  }> {\n    this.#assertOpen();\n\n    const annotations: Annotation[] = [];\n    const recordStarts: (number | null)[] = new Array<number | null>(this.recordCount).fill(null);\n    let malformed = 0;\n    let malformedTimekeeping = 0;\n    let unreadableDurations = 0;\n\n    const channels = this.annotationSignals;\n    if (channels.length === 0) {\n      return { annotations, recordStarts, malformed, malformedTimekeeping, unreadableDurations };\n    }\n\n    const { headerBytes, recordBytes, bytesPerSample } = this.header;\n    const buffers = channels.map((c) => Buffer.alloc(c.samplesPerRecord * bytesPerSample));\n    const timekeeping = this.timekeepingSignal;\n\n    for (let record = 0; record < this.recordCount; record++) {\n      for (const [position, channel] of channels.entries()) {\n        const buffer = buffers[position];\n        if (!buffer || buffer.length === 0) continue;\n\n        const offset = headerBytes + record * recordBytes + channel.byteOffsetInRecord;\n        const bytesRead = await readFully(this.#handle, buffer, 0, buffer.length, offset);\n        if (bytesRead < buffer.length) {\n          throw changedWhileReading(record, buffer.length, bytesRead, 'annotation data');\n        }\n\n        // Only the timekeeping channel carries the record's start; see timekeepingSignal.\n        const decoded = decodeRecordAnnotations(buffer, record, channel === timekeeping);\n        if (channel === timekeeping) recordStarts[record] = decoded.recordStart;\n        for (const annotation of decoded.annotations) annotations.push(annotation);\n        malformed += decoded.malformed;\n        malformedTimekeeping += decoded.malformedTimekeeping;\n        unreadableDurations += decoded.unreadableDurations;\n      }\n    }\n\n    annotations.sort((a, b) => a.onset - b.onset || a.recordIndex - b.recordIndex);\n    return { annotations, recordStarts, malformed, malformedTimekeeping, unreadableDurations };\n  }\n\n  async close(): Promise<void> {\n    if (this.#closed) return;\n    this.#closed = true;\n    await this.#handle.close();\n  }\n\n  #assertOpen(): void {\n    if (this.#closed) throw new EdfError('UNREADABLE', 'This EDF file has already been closed.');\n  }\n}\n\nfunction describe(cause: unknown): string {\n  if (cause instanceof Error) {\n    const code = (cause as NodeJS.ErrnoException).code;\n    if (code === 'ENOENT') return 'no such file';\n    if (code === 'EACCES') return 'permission denied';\n    return cause.message;\n  }\n  return String(cause);\n}\n\n/**\n * The most `fs.read` will accept as a length.\n *\n * Node asserts on a length that does not fit in a signed 32-bit integer, and it asserts in\n * C++: `Assertion failed: args[3]->IsInt32()`, forty frames of native stack, SIGABRT. Not an\n * exception — nothing in JavaScript sees it, so no catch block and no `uncaughtException`\n * handler runs, and a library consumer's whole process goes down with it.\n *\n * A round gigabyte rather than the exact limit, so the loop below does whole even reads.\n */\nconst MAX_READ_BYTES = 1024 * 1024 * 1024;\n\n/** Fill a requested region unless EOF is reached; regular-file reads may legally be short. */\nasync function readFully(\n  handle: FileHandle,\n  buffer: Buffer,\n  offset: number,\n  length: number,\n  position: number,\n): Promise<number> {\n  let total = 0;\n  while (total < length) {\n    /*\n      Capped, because one data record can be larger than a single read may be.\n\n      A record is read in one call when it exceeds the chunk budget — there is nothing\n      smaller to divide it by, since a record is the unit the format is addressed in. EDF's\n      samples-per-record field is 8 characters, so eleven channels at 99,999,999 samples make\n      a record of 2.2 GB, and a long record duration at ordinary rates gets there too. That\n      went to `fs.read` as a single length over 2^31-1 and took the process out with a native\n      assertion rather than an error.\n\n      Looping was already how a short read is handled, so the cap costs one more iteration\n      per gigabyte and nothing else.\n    */\n    const want = Math.min(length - total, MAX_READ_BYTES);\n    const { bytesRead } = await handle.read(buffer, offset + total, want, position + total);\n    if (bytesRead === 0) break;\n    total += bytesRead;\n  }\n  return total;\n}\n\nfunction changedWhileReading(\n  record: number,\n  expected: number,\n  actual: number,\n  subject = 'data',\n): EdfError {\n  return new EdfError(\n    'UNREADABLE',\n    `Expected ${expected} bytes of ${subject} at record ${record} but only ${actual} were ` +\n      `available; the file appears to have changed size while it was being read.`,\n    'Make sure the recording is not still being written to, then try again.',\n  );\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edf2csv",
-  "version": "0.5.54",
+  "version": "0.5.55",
   "description": "Convert EDF, EDF+ and BDF biosignal recordings (European Data Format) to CSV from the command line. Local, streaming, and never resamples or alters units.",
   "keywords": [
     "edf",