edf2csv 0.7.209 → 0.7.211

package/dist/convert/options.d.ts

@@ -18,6 +18,19 @@
 export declare class OptionError extends Error {
     constructor(message: string);
 }
+/**
+ * The largest `--decimals` accepts, and what both documentation pages state.
+ *
+ * Not a limit of `toFixed`, whatever this comment used to say. `toFixed` takes 0 to 100 and
+ * throws a RangeError at 101 — which is exactly the belief `MAX_DERIVED_DECIMALS` in
+ * edf/scale.ts exists to correct, having once clamped the *derived* precision to 20 on the
+ * same wrong grounds and rounded a magnetometer channel needing 23 places onto a grid three
+ * digital codes wide, losing 69% of its samples in silence.
+ *
+ * Twenty is a bound on a number a person types by hand, not on what the format can express.
+ * The derived precision, which nobody types, runs to 100 and says so.
+ */
+export declare const MAX_DECIMALS = 20;
 export declare function assertOptions(options: {
     decimals?: number | undefined;
     start?: number | undefined;

package/dist/convert/options.js

@@ -33,7 +33,7 @@ export class OptionError extends Error {
  * Twenty is a bound on a number a person types by hand, not on what the format can express.
  * The derived precision, which nobody types, runs to 100 and says so.
  */
-const MAX_DECIMALS = 20;
+export const MAX_DECIMALS = 20;
 export function assertOptions(options) {
     const { decimals } = options;
     if (decimals !== undefined) {

package/dist/convert/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/convert/options.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Checking the options a caller passed, before anything is written.\n *\n * The command line has always validated these — `--decimals 1.5` is a usage error and always\n * has been — and the library did not, so the same value behaved differently depending on how\n * it arrived. `convert(file, { decimals: NaN })` resolved successfully having written whole\n * numbers into a column the caller had asked for decimals in, which is the worst of the\n * three: no error, no warning, and output that looks like a deliberate choice. `decimals: -1`\n * reached `toFixed` and came back as a bare RangeError from deep inside the formatter, naming\n * nothing the caller had written. `start: NaN` created the output directory, wrote\n * signals.csv, and then failed with a message about the input being unreadable — a partial\n * conversion, blamed on the file.\n *\n * These run at the top of `buildPlan`, which every path goes through before a directory is\n * created or a stream is opened, so a rejected option leaves nothing behind.\n */\n\n/** A problem with the options a caller passed, as opposed to a problem with the file. */\nexport class OptionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'OptionError';\n  }\n}\n\n/**\n * The largest `--decimals` accepts, and what both documentation pages state.\n *\n * Not a limit of `toFixed`, whatever this comment used to say. `toFixed` takes 0 to 100 and\n * throws a RangeError at 101 — which is exactly the belief `MAX_DERIVED_DECIMALS` in\n * edf/scale.ts exists to correct, having once clamped the *derived* precision to 20 on the\n * same wrong grounds and rounded a magnetometer channel needing 23 places onto a grid three\n * digital codes wide, losing 69% of its samples in silence.\n *\n * Twenty is a bound on a number a person types by hand, not on what the format can express.\n * The derived precision, which nobody types, runs to 100 and says so.\n */\nconst MAX_DECIMALS = 20;\n\nexport function assertOptions(options: {\n  decimals?: number | undefined;\n  start?: number | undefined;\n  duration?: number | undefined;\n  end?: number | undefined;\n  layout?: string | undefined;\n  channels?: readonly string[] | undefined;\n  outputDir?: string | undefined;\n}): void {\n  const { decimals } = options;\n  if (decimals !== undefined) {\n    if (!Number.isInteger(decimals) || decimals < 0 || decimals > MAX_DECIMALS) {\n      throw new OptionError(\n        `decimals must be a whole number between 0 and ${MAX_DECIMALS}, got ${describe(decimals)}.`,\n      );\n    }\n  }\n\n  /*\n    `start` and `end` are positions on the recording's own clock, `duration` is a length.\n\n    All three were held above zero, which is right for a length and wrong for a position: a\n    recording timed from its first record's timekeeping annotation may sit before zero, and\n    -100 is then where its first sample is. So a caller could read `plan.range` back as\n    `recordingStartSeconds: -100` and not be allowed to ask for it — the same wall\n    `parseTimeSpec` put in front of the command line until 0.5.120.\n\n    Non-finite is still refused for all three, since NaN reaches a comparison as false and\n    would take the whole recording without saying so.\n  */\n  for (const name of ['start', 'duration', 'end'] as const) {\n    const value = options[name];\n    if (value === undefined) continue;\n    if (typeof value !== 'number' || !Number.isFinite(value)) {\n      throw new OptionError(`${name} must be a number of seconds, got ${describe(value)}.`);\n    }\n    /*\n      A length below zero is refused for what it is, rather than for not being a number.\n\n      `duration: -1` came back as \"duration must be a number of seconds, got -1\", which is\n      not the reason and not true: -1 is a number of seconds, and this same call accepts it\n      for `start` and for `end`, where a recording timed from before zero makes it an\n      ordinary position. What is wrong is that a duration is a length, and no length is\n      negative — which is what the command line says for the same value, and what the API\n      reference has always said this check enforces.\n    */\n    if (name === 'duration' && value < 0) {\n      throw new OptionError(`duration is a length of time, so it cannot be ${describe(value)}.`);\n    }\n  }\n\n  /*\n    Two words, and a caller who writes a third means something the tool cannot do.\n\n    The command line has always rejected `--layout tall`. The library took it, put it in\n    `plan.layout` for the caller to read back, and wrote the wide layout — so a programmatic\n    caller with a typo got a conversion that was not the one they asked for, described by a\n    plan that agreed with the typo. Every other option that has a shape is checked here; this\n    one was added in 0.5.0 and never joined them.\n  */\n  const { layout } = options;\n  if (layout !== undefined && layout !== 'wide' && layout !== 'long') {\n    throw new OptionError(`layout must be \"wide\" or \"long\", got ${describe(layout)}.`);\n  }\n\n  /*\n    A selection that names nothing is not the absence of a selection.\n\n    `buildPlan` asks `options.channels.length > 0` before selecting, so an empty array fell\n    through to the branch that means \"no channels option was given\" — and `convert(file, {\n    channels: [] })` wrote every channel in the recording, resolved, and said nothing. That is\n    the one shape of this the command line has always refused, in as many words: \"Returning\n    undefined here would mean 'no --channels given' and convert everything, which is the\n    opposite of what someone passing an empty list is asking for.\"\n\n    A list of blanks is the same request written differently — it is what `''.split(',')`\n    produces, which is how a caller building the array from user input arrives here — and it\n    reached `selectChannels` and came back \"No channels were selected\", a sentence about the\n    file rather than about the call. Both are the option being wrong, so both are refused\n    here, before a directory exists.\n  */\n  /*\n    An empty destination, refused here rather than by the filesystem.\n\n    `convert(file, { outputDir: '' })` went the whole way to `mkdir('')` and came back a\n    `ConversionError`: \"Cannot create \\\"\\\": part of the path does not exist. Check the path\n    exists and that you have permission to write there.\" Advice about a path and a permission\n    for a value that is neither, and a failure class that means the conversion went wrong\n    where the option did.\n\n    The command line refused this at 0.6.x, with the reasoning that `--out \"$DEST\"` and `DEST`\n    unset is how it gets written by accident — and left the library, which a caller building\n    the path in code reaches the same way. Not trimmed, for the reason given there: a\n    directory whose name is a space is a strange thing to ask for, but it is a thing the\n    filesystem has and a path is not a keyword.\n  */\n  if (options.outputDir === '') {\n    throw new OptionError('outputDir is empty. Give a directory, for example \"./converted\".');\n  }\n\n  const { channels } = options;\n  if (channels !== undefined) {\n    /*\n      A list of strings, checked as one. `selectChannels` calls `.trim()` on every term, so a\n      caller who passed the string `'ECG'` had it iterated character by character and was told\n      `No channel named \"E\"`, and one who passed `[1]` — a position, reasonably enough — got\n      `TypeError: rawTerm.trim is not a function` out of the middle of the selector, naming\n      nothing they had written. Both are the option being the wrong shape, which is the case\n      this function exists for.\n    */\n    if (!Array.isArray(channels) || channels.some((term) => typeof term !== 'string')) {\n      throw new OptionError(`channels must be a list of channel names, got ${describe(channels)}.`);\n    }\n    if (channels.every((term) => term.trim() === '')) {\n      throw new OptionError('channels was given but lists no channel names.');\n    }\n  }\n}\n\n/**\n * The recording to read, checked before it is opened.\n *\n * `EdfFile.open` hands whatever it is given to `fs`, and the refusal comes back as an\n * `EdfError` coded `UNREADABLE`, hinted \"Check the path is spelled the way it is on disk and\n * that you have permission to read it\" — advice about a path, over a value that is not one,\n * filed as a problem with the recording rather than with the call. `convert({ input: 'a.edf' })`,\n * which is the option-bag shape the second parameter has, answered `Cannot read \"[object\n * Object]\"`; `convert(['a.edf', 'b.edf'])` answered `Cannot read \"a.edf,b.edf\"`, a path the\n * caller never wrote, because `String` of an array joins it with commas.\n *\n * The empty string is left to `fs`, which has no such file and says so truthfully — the same\n * reasoning `outputDir` states for not trimming: a path is not a keyword.\n */\nexport function assertInputPath(input: unknown): void {\n  if (typeof input !== 'string') {\n    throw new OptionError(`input must be a path to a recording, got ${describe(input)}.`);\n  }\n}\n\n/** `NaN` and `-1` read better unquoted; anything else is quoted so its type is visible. */\nfunction describe(value: unknown): string {\n  return typeof value === 'number' ? String(value) : JSON.stringify(value);\n}\n"]}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/convert/options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,yFAAyF;AACzF,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAE/B,MAAM,UAAU,aAAa,CAAC,OAQ7B;IACC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC7B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,GAAG,YAAY,EAAE,CAAC;YAC3E,MAAM,IAAI,WAAW,CACnB,iDAAiD,YAAY,SAAS,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAC5F,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;;;;MAWE;IACF,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,CAAU,EAAE,CAAC;QACzD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,WAAW,CAAC,GAAG,IAAI,qCAAqC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxF,CAAC;QACD;;;;;;;;;UASE;QACF,IAAI,IAAI,KAAK,UAAU,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,WAAW,CAAC,iDAAiD,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC;IAED;;;;;;;;MAQE;IACF,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC3B,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACnE,MAAM,IAAI,WAAW,CAAC,wCAAwC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;;;;;;;;;;MAeE;IACF;;;;;;;;;;;;;;MAcE;IACF,IAAI,OAAO,CAAC,SAAS,KAAK,EAAE,EAAE,CAAC;QAC7B,MAAM,IAAI,WAAW,CAAC,kEAAkE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC7B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B;;;;;;;UAOE;QACF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;YAClF,MAAM,IAAI,WAAW,CAAC,iDAAiD,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAChG,CAAC;QACD,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,WAAW,CAAC,gDAAgD,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,WAAW,CAAC,4CAA4C,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACxF,CAAC;AACH,CAAC;AAED,2FAA2F;AAC3F,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC","sourcesContent":["/**\n * Checking the options a caller passed, before anything is written.\n *\n * The command line has always validated these — `--decimals 1.5` is a usage error and always\n * has been — and the library did not, so the same value behaved differently depending on how\n * it arrived. `convert(file, { decimals: NaN })` resolved successfully having written whole\n * numbers into a column the caller had asked for decimals in, which is the worst of the\n * three: no error, no warning, and output that looks like a deliberate choice. `decimals: -1`\n * reached `toFixed` and came back as a bare RangeError from deep inside the formatter, naming\n * nothing the caller had written. `start: NaN` created the output directory, wrote\n * signals.csv, and then failed with a message about the input being unreadable — a partial\n * conversion, blamed on the file.\n *\n * These run at the top of `buildPlan`, which every path goes through before a directory is\n * created or a stream is opened, so a rejected option leaves nothing behind.\n */\n\n/** A problem with the options a caller passed, as opposed to a problem with the file. */\nexport class OptionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'OptionError';\n  }\n}\n\n/**\n * The largest `--decimals` accepts, and what both documentation pages state.\n *\n * Not a limit of `toFixed`, whatever this comment used to say. `toFixed` takes 0 to 100 and\n * throws a RangeError at 101 — which is exactly the belief `MAX_DERIVED_DECIMALS` in\n * edf/scale.ts exists to correct, having once clamped the *derived* precision to 20 on the\n * same wrong grounds and rounded a magnetometer channel needing 23 places onto a grid three\n * digital codes wide, losing 69% of its samples in silence.\n *\n * Twenty is a bound on a number a person types by hand, not on what the format can express.\n * The derived precision, which nobody types, runs to 100 and says so.\n */\nexport const MAX_DECIMALS = 20;\n\nexport function assertOptions(options: {\n  decimals?: number | undefined;\n  start?: number | undefined;\n  duration?: number | undefined;\n  end?: number | undefined;\n  layout?: string | undefined;\n  channels?: readonly string[] | undefined;\n  outputDir?: string | undefined;\n}): void {\n  const { decimals } = options;\n  if (decimals !== undefined) {\n    if (!Number.isInteger(decimals) || decimals < 0 || decimals > MAX_DECIMALS) {\n      throw new OptionError(\n        `decimals must be a whole number between 0 and ${MAX_DECIMALS}, got ${describe(decimals)}.`,\n      );\n    }\n  }\n\n  /*\n    `start` and `end` are positions on the recording's own clock, `duration` is a length.\n\n    All three were held above zero, which is right for a length and wrong for a position: a\n    recording timed from its first record's timekeeping annotation may sit before zero, and\n    -100 is then where its first sample is. So a caller could read `plan.range` back as\n    `recordingStartSeconds: -100` and not be allowed to ask for it — the same wall\n    `parseTimeSpec` put in front of the command line until 0.5.120.\n\n    Non-finite is still refused for all three, since NaN reaches a comparison as false and\n    would take the whole recording without saying so.\n  */\n  for (const name of ['start', 'duration', 'end'] as const) {\n    const value = options[name];\n    if (value === undefined) continue;\n    if (typeof value !== 'number' || !Number.isFinite(value)) {\n      throw new OptionError(`${name} must be a number of seconds, got ${describe(value)}.`);\n    }\n    /*\n      A length below zero is refused for what it is, rather than for not being a number.\n\n      `duration: -1` came back as \"duration must be a number of seconds, got -1\", which is\n      not the reason and not true: -1 is a number of seconds, and this same call accepts it\n      for `start` and for `end`, where a recording timed from before zero makes it an\n      ordinary position. What is wrong is that a duration is a length, and no length is\n      negative — which is what the command line says for the same value, and what the API\n      reference has always said this check enforces.\n    */\n    if (name === 'duration' && value < 0) {\n      throw new OptionError(`duration is a length of time, so it cannot be ${describe(value)}.`);\n    }\n  }\n\n  /*\n    Two words, and a caller who writes a third means something the tool cannot do.\n\n    The command line has always rejected `--layout tall`. The library took it, put it in\n    `plan.layout` for the caller to read back, and wrote the wide layout — so a programmatic\n    caller with a typo got a conversion that was not the one they asked for, described by a\n    plan that agreed with the typo. Every other option that has a shape is checked here; this\n    one was added in 0.5.0 and never joined them.\n  */\n  const { layout } = options;\n  if (layout !== undefined && layout !== 'wide' && layout !== 'long') {\n    throw new OptionError(`layout must be \"wide\" or \"long\", got ${describe(layout)}.`);\n  }\n\n  /*\n    A selection that names nothing is not the absence of a selection.\n\n    `buildPlan` asks `options.channels.length > 0` before selecting, so an empty array fell\n    through to the branch that means \"no channels option was given\" — and `convert(file, {\n    channels: [] })` wrote every channel in the recording, resolved, and said nothing. That is\n    the one shape of this the command line has always refused, in as many words: \"Returning\n    undefined here would mean 'no --channels given' and convert everything, which is the\n    opposite of what someone passing an empty list is asking for.\"\n\n    A list of blanks is the same request written differently — it is what `''.split(',')`\n    produces, which is how a caller building the array from user input arrives here — and it\n    reached `selectChannels` and came back \"No channels were selected\", a sentence about the\n    file rather than about the call. Both are the option being wrong, so both are refused\n    here, before a directory exists.\n  */\n  /*\n    An empty destination, refused here rather than by the filesystem.\n\n    `convert(file, { outputDir: '' })` went the whole way to `mkdir('')` and came back a\n    `ConversionError`: \"Cannot create \\\"\\\": part of the path does not exist. Check the path\n    exists and that you have permission to write there.\" Advice about a path and a permission\n    for a value that is neither, and a failure class that means the conversion went wrong\n    where the option did.\n\n    The command line refused this at 0.6.x, with the reasoning that `--out \"$DEST\"` and `DEST`\n    unset is how it gets written by accident — and left the library, which a caller building\n    the path in code reaches the same way. Not trimmed, for the reason given there: a\n    directory whose name is a space is a strange thing to ask for, but it is a thing the\n    filesystem has and a path is not a keyword.\n  */\n  if (options.outputDir === '') {\n    throw new OptionError('outputDir is empty. Give a directory, for example \"./converted\".');\n  }\n\n  const { channels } = options;\n  if (channels !== undefined) {\n    /*\n      A list of strings, checked as one. `selectChannels` calls `.trim()` on every term, so a\n      caller who passed the string `'ECG'` had it iterated character by character and was told\n      `No channel named \"E\"`, and one who passed `[1]` — a position, reasonably enough — got\n      `TypeError: rawTerm.trim is not a function` out of the middle of the selector, naming\n      nothing they had written. Both are the option being the wrong shape, which is the case\n      this function exists for.\n    */\n    if (!Array.isArray(channels) || channels.some((term) => typeof term !== 'string')) {\n      throw new OptionError(`channels must be a list of channel names, got ${describe(channels)}.`);\n    }\n    if (channels.every((term) => term.trim() === '')) {\n      throw new OptionError('channels was given but lists no channel names.');\n    }\n  }\n}\n\n/**\n * The recording to read, checked before it is opened.\n *\n * `EdfFile.open` hands whatever it is given to `fs`, and the refusal comes back as an\n * `EdfError` coded `UNREADABLE`, hinted \"Check the path is spelled the way it is on disk and\n * that you have permission to read it\" — advice about a path, over a value that is not one,\n * filed as a problem with the recording rather than with the call. `convert({ input: 'a.edf' })`,\n * which is the option-bag shape the second parameter has, answered `Cannot read \"[object\n * Object]\"`; `convert(['a.edf', 'b.edf'])` answered `Cannot read \"a.edf,b.edf\"`, a path the\n * caller never wrote, because `String` of an array joins it with commas.\n *\n * The empty string is left to `fs`, which has no such file and says so truthfully — the same\n * reasoning `outputDir` states for not trimming: a path is not a keyword.\n */\nexport function assertInputPath(input: unknown): void {\n  if (typeof input !== 'string') {\n    throw new OptionError(`input must be a path to a recording, got ${describe(input)}.`);\n  }\n}\n\n/** `NaN` and `-1` read better unquoted; anything else is quoted so its type is visible. */\nfunction describe(value: unknown): string {\n  return typeof value === 'number' ? String(value) : JSON.stringify(value);\n}\n"]}

package/dist/convert/run.js

@@ -540,21 +540,6 @@ async function writeSignalFiles(file, plan, outputDir, recordStarts, options, on
 function nearlyEqual(a, b) {
     return Math.abs(a - b) <= Math.max(Math.abs(a), Math.abs(b)) * 1e-12;
 }
-/** The chosen instant as it will be written, for deciding which channels share it. */
-function formatAt(open, cursors, recordStart, earliest) {
-    for (let g = 0; g < open.length; g++) {
-        const entry = open[g];
-        if (!entry)
-            continue;
-        const sample = cursors[g] ?? 0;
-        if (sample >= entry.group.samplesPerRecord)
-            continue;
-        if (recordStart + sample / entry.group.rate === earliest) {
-            return entry.formatTime(recordStart, sample);
-        }
-    }
-    return '';
-}
 async function writeLongRecord(file, open, batch, recordInBatch, recordStart, range) {
     const writer = open[0]?.writer;
     if (!writer)
@@ -564,6 +549,8 @@ async function writeLongRecord(file, open, batch, recordInBatch, recordStart, ra
     const due = [];
     for (;;) {
         let earliest = Infinity;
+        let source = -1;
+        let sourceSample = 0;
         for (let g = 0; g < open.length; g++) {
             const entry = open[g];
             if (!entry)
@@ -572,8 +559,11 @@ async function writeLongRecord(file, open, batch, recordInBatch, recordStart, ra
             if (sample >= entry.group.samplesPerRecord)
                 continue;
             const time = recordStart + sample / entry.group.rate;
-            if (time < earliest)
+            if (time < earliest) {
                 earliest = time;
+                source = g;
+                sourceSample = sample;
+            }
         }
         if (earliest === Infinity)
             return;
@@ -596,7 +586,15 @@ async function writeLongRecord(file, open, batch, recordInBatch, recordStart, ra
           definition a reader of the CSV can apply. The numeric pre-filter keeps the common case
           to one comparison; formatting happens only for candidates already within a hair.
         */
-        const earliestText = formatAt(open, cursors, recordStart, earliest);
+        let earliestText = null;
+        /*
+          Formatted on the first near-tie and not before, which on a single-rate table is never.
+    
+          The group and sample that set `earliest` are captured above rather than searched for
+          again, since the loop below advances cursors as it goes and a later search would be
+          looking at a table that had already moved on.
+        */
+        const asWritten = () => (earliestText ??= open[source]?.formatTime(recordStart, sourceSample) ?? '');
         due.length = 0;
         for (let g = 0; g < open.length; g++) {
             const entry = open[g];
@@ -610,7 +608,7 @@ async function writeLongRecord(file, open, batch, recordInBatch, recordStart, ra
                 // Far away in the ordinary case; only a near-tie is worth formatting.
                 if (!nearlyEqual(time, earliest))
                     continue;
-                if (entry.formatTime(recordStart, sample) !== earliestText)
+                if (entry.formatTime(recordStart, sample) !== asWritten())
                     continue;
             }
             cursors[g] = sample + 1;