@juspay/neurolink 10.10.9 → 10.10.11

package/dist/cli/factories/commandFactory.js

@@ -228,6 +228,11 @@ export class CLICommandFactory {
             type: "number",
             description: "Wall-clock cap (ms) for CSV parsing; returns partial rows on timeout (#379).",
         },
+        "csv-skip-empty-lines": {
+            type: "boolean",
+            default: true,
+            description: "Skip blank/whitespace-only CSV data rows in content and rowCount (default true). Use --no-csv-skip-empty-lines to preserve them (#373).",
+        },
         model: {
             type: "string",
             description: "Specific model to use (e.g. gemini-2.5-pro, gemini-2.5-flash)",
@@ -2441,6 +2446,7 @@ export class CLICommandFactory {
             sanitizeColumnNames: argv.csvSanitizeNames,
             columnNameCase: argv.csvNameCase,
             parseTimeoutMs: argv.csvParseTimeoutMs,
+            skipEmptyLines: argv.csvSkipEmptyLines,
         };
     }
     /**

package/dist/lib/processors/media/AudioProcessor.js

@@ -41,6 +41,7 @@ import { SIZE_LIMITS_MB } from "../config/index.js";
 import { FileErrorCode } from "../errors/index.js";
 import { withTimeout } from "../../utils/timeout.js";
 import { formatMediaDuration } from "../../utils/mediaDuration.js";
+import { logger } from "../../utils/logger.js";
 import { tryImport } from "../../utils/tryImport.js";
 let _musicMetadata = null;
 async function loadMusicMetadata() {
@@ -264,6 +265,11 @@ export class AudioProcessor extends BaseFileProcessor {
                     transcript: transcriptionResult.transcript,
                     hasTranscript: transcriptionResult.hasTranscript,
                     transcriptionProvider: transcriptionResult.transcriptionProvider,
+                    ...(transcriptionResult.transcriptionSkippedReason
+                        ? {
+                            transcriptionSkippedReason: transcriptionResult.transcriptionSkippedReason,
+                        }
+                        : {}),
                     coverArt: coverArt ?? undefined,
                     buffer,
                     mimetype: fileInfo.mimetype || "audio/mpeg",
@@ -316,20 +322,25 @@ export class AudioProcessor extends BaseFileProcessor {
      * @returns Transcription result with transcript text, or empty result
      */
     async attemptTranscription(buffer, filename, mimetype) {
-        const emptyResult = {
-            transcript: undefined,
-            hasTranscript: false,
-            transcriptionProvider: undefined,
+        const skipped = (reason) => {
+            logger.warn(`[AudioProcessor] No transcript for ${filename}: ${reason}. ` +
+                `The model will receive metadata only.`);
+            return {
+                transcript: undefined,
+                hasTranscript: false,
+                transcriptionProvider: undefined,
+                transcriptionSkippedReason: reason,
+            };
         };
         // Check if OPENAI_API_KEY is available
         const apiKey = process.env.OPENAI_API_KEY;
         if (!apiKey) {
-            return emptyResult;
+            return skipped("OPENAI_API_KEY is not set, and Whisper is the only transcription backend wired up");
         }
         // Check file size (Whisper limit is 25MB)
         const fileSizeMB = buffer.length / (1024 * 1024);
         if (fileSizeMB > AUDIO_CONFIG.WHISPER_MAX_SIZE_MB) {
-            return emptyResult;
+            return skipped(`file is ${fileSizeMB.toFixed(1)}MB, over Whisper's ${AUDIO_CONFIG.WHISPER_MAX_SIZE_MB}MB limit — split or compress it`);
         }
         // Check if file format is supported by Whisper
         const ext = filename.split(".").pop()?.toLowerCase();
@@ -343,7 +354,7 @@ export class AudioProcessor extends BaseFileProcessor {
                 mimetype.startsWith("audio/ogg") ||
                 mimetype.startsWith("audio/x-m4a"));
         if (!isFormatSupported && !isMimeSupported) {
-            return emptyResult;
+            return skipped(`format is not one Whisper accepts (extension "${ext ?? "none"}", mimetype "${mimetype ?? "none"}"); supported: ${AUDIO_CONFIG.WHISPER_SUPPORTED_FORMATS.join(", ")}`);
         }
         try {
             // Dynamic imports to avoid loading these modules when transcription is not needed
@@ -351,26 +362,33 @@ export class AudioProcessor extends BaseFileProcessor {
             const openai = createOpenAI({ apiKey });
             const model = openai.transcription("whisper-1");
             // Wrap in withTimeout — large audio files can take a while, but a
-            // stalled request shouldn't block the processor forever. The outer
-            // catch swallows any error (transcription is best-effort), so a
-            // TimeoutError ends up in the same fallback path as other failures.
+            // stalled request shouldn't block the processor forever. A TimeoutError
+            // lands in the same handler as other failures below, which reports it as
+            // the reason rather than discarding it.
             const result = await withTimeout(experimental_transcribe({
                 model,
                 audio: buffer,
             }), AUDIO_CONFIG.TRANSCRIPTION_TIMEOUT_MS, "openai-whisper", "generate");
             if (result.text && result.text.trim().length > 0) {
+                logger.debug(`[AudioProcessor] Transcribed ${filename} via openai-whisper (${result.text.trim().length} chars)`);
                 return {
                     transcript: result.text.trim(),
                     hasTranscript: true,
                     transcriptionProvider: "openai-whisper",
+                    transcriptionSkippedReason: undefined,
                 };
             }
-            return emptyResult;
+            // A successful call that returned nothing is a legitimate outcome
+            // (silence, music, no speech) — distinct from a failure.
+            return skipped("Whisper returned an empty transcript for this audio");
         }
-        catch {
-            // Transcription is best-effort — never fail the entire processing pipeline
-            // Common failures: rate limiting, network issues, unsupported audio encoding
-            return emptyResult;
+        catch (error) {
+            // Transcription stays best-effort — a failure must never kill the whole
+            // processing pipeline. But discarding the error outright, as this block
+            // used to, made a bad API key, a rate limit and a network blip all look
+            // identical to "this file has no speech in it".
+            const message = error instanceof Error ? error.message : String(error);
+            return skipped(`transcription request failed — ${message}`);
         }
     }
     // ===========================================================================

package/dist/lib/types/file.d.ts

@@ -200,6 +200,12 @@ export type CSVProcessorOptions = {
      * rather than hanging forever. Defaults: 30s for strings, 5min for files.
      */
     parseTimeoutMs?: number;
+    /**
+     * Skip blank / whitespace-only data rows (#373). Default `true`: blank lines
+     * are excluded from the returned content (including raw CSV text) and from
+     * `metadata.rowCount`. Set to `false` to preserve empty lines literally.
+     */
+    skipEmptyLines?: boolean;
 };
 /**
  * PDF API types for different providers

package/dist/lib/types/processor.d.ts

@@ -703,6 +703,12 @@ export type ProcessedAudio = ProcessedFileBase & {
     transcript?: string;
     hasTranscript: boolean;
     transcriptionProvider?: string;
+    /**
+     * Why transcription produced nothing, when it did (#416). Absent on success.
+     * Lets a caller distinguish "this audio has no speech" from "the transcription
+     * backend was never reachable", which previously looked identical.
+     */
+    transcriptionSkippedReason?: string;
     coverArt?: Buffer;
 };
 /**

package/dist/lib/utils/csvProcessor.d.ts

@@ -30,6 +30,18 @@ export declare function isValidCsvRow(row: unknown): row is CSVRow;
  * match) when a row violates the invariant.
  */
 export declare function assertValidCsvRow(row: unknown, rowNumber: number): asserts row is CSVRow;
+/**
+ * True when a parsed CSV row is blank: no keys, or every value is empty /
+ * whitespace-only (#373). Shared by the structured post-filter and by
+ * `streamParse` so blank rows do not consume `maxRows`.
+ */
+export declare function isBlankCsvDataRow(row: CSVRow): boolean;
+/**
+ * Raw-line counterpart of {@link isBlankCsvDataRow} (#373): a fully blank /
+ * whitespace line, or a delimiter-only line such as `,,` / `  ,  ` whose
+ * fields are all empty after a CSV-aware split.
+ */
+export declare function isBlankCsvRawLine(line: string, delimiter: string): boolean;
 /**
  * Detect if first line is CSV metadata (not actual data/headers)
  * Common patterns:
@@ -174,11 +186,17 @@ export declare class CSVProcessor {
     /**
      * Format parsed CSV data for LLM consumption
      * Only used for JSON and Markdown formats (raw format handled separately)
+     *
+     * @param columnNames - Optional schema headers (#373). When preserved blank
+     *   rows lead `rows`, Markdown must still use the real column names.
      */
     private static formatForLLM;
     /**
      * Format as markdown table
      * Best for small datasets (<100 rows)
+     *
+     * @param columnNames - Optional explicit headers (#373). Falls back to
+     *   `Object.keys(rows[0])` when omitted.
      */
     private static toMarkdownTable;
     /**
@@ -187,6 +205,7 @@ export declare class CSVProcessor {
      * @param sampleRows - Array of sample row objects
      * @param format - Output format for sample data
      * @param includeHeaders - Whether to include headers in CSV/markdown formats
+     * @param columnNames - Optional schema headers for csv/markdown (#373)
      * @returns Formatted sample data as string or array
      */
     private static formatSampleData;
@@ -195,6 +214,7 @@ export declare class CSVProcessor {
      *
      * @param rows - Array of row objects
      * @param includeHeaders - Whether to include header row
+     * @param columnNames - Optional explicit headers (#373)
      * @returns CSV formatted string
      */
     private static toCSVString;

package/dist/lib/utils/csvProcessor.js

@@ -180,6 +180,37 @@ export function assertValidCsvRow(row, rowNumber) {
         throw ErrorFactory.csvRowInvalid(`[CSVProcessor] Invalid CSV row ${rowNumber}: expected a string-keyed object with string values, got ${Array.isArray(row) ? "array" : typeof row}`, rowNumber);
     }
 }
+/**
+ * True when a parsed CSV row is blank: no keys, or every value is empty /
+ * whitespace-only (#373). Shared by the structured post-filter and by
+ * `streamParse` so blank rows do not consume `maxRows`.
+ */
+export function isBlankCsvDataRow(row) {
+    const keys = Object.keys(row);
+    if (keys.length === 0) {
+        return true;
+    }
+    return Object.values(row).every((val) => val === "" || (typeof val === "string" && val.trim() === ""));
+}
+/**
+ * Raw-line counterpart of {@link isBlankCsvDataRow} (#373): a fully blank /
+ * whitespace line, or a delimiter-only line such as `,,` / `  ,  ` whose
+ * fields are all empty after a CSV-aware split.
+ */
+export function isBlankCsvRawLine(line, delimiter) {
+    if (line.trim() === "") {
+        return true;
+    }
+    const fields = splitCSVFields(line, delimiter);
+    if (fields.length === 0) {
+        return true;
+    }
+    const row = Object.create(null);
+    for (let i = 0; i < fields.length; i++) {
+        row[`c${i}`] = fields[i];
+    }
+    return isBlankCsvDataRow(row);
+}
 // ============================================================================
 // Parse Error Context (#375)
 // ============================================================================
@@ -624,18 +655,41 @@ function isMetadataLine(lines) {
     }
     const firstLine = lines[0].trim();
     const secondLine = lines[1].trim();
+    // Excel's explicit-delimiter preamble is metadata regardless of what follows.
     if (firstLine.match(/^sep=/i)) {
         return true;
     }
+    // #373: this check has to come BEFORE the comma-count heuristics, not after.
+    // Both of them read a higher comma count on line 2 as "line 1 was a preamble"
+    // — but a delimiter-only row (`,,`) is a blank DATA row, and its commas are
+    // structure, not fields. Ordered the other way, a legitimate single-column
+    // header followed by a blank row (`name` / `,,`) tripped the zero-vs-nonzero
+    // rule and stripMetadataLine() deleted the real header, leaving unnamed
+    // columns. Verified against `name\n,,\nalice\nbob`.
+    if (isDelimiterOnlyOrBlankLine(secondLine)) {
+        return false;
+    }
     const firstCommaCount = countUnquotedCommas(firstLine);
     const secondCommaCount = countUnquotedCommas(secondLine);
+    // A title/preamble line carries no delimiters while the header below it does.
     if (firstCommaCount === 0 && secondCommaCount > 0) {
         return true;
     }
-    if (secondCommaCount > 0 && firstCommaCount !== secondCommaCount) {
+    // Differing field counts mean line 1 is not part of the same table as line 2.
+    return secondCommaCount > 0 && firstCommaCount !== secondCommaCount;
+}
+/**
+ * True when `line` is empty/whitespace or contains only common CSV
+ * delimiters (comma / tab / semicolon / pipe) and whitespace — i.e. a
+ * delimiter-only blank row like `,,` or `  ;  ;  `. Used before the
+ * delimiter is known (metadata detection).
+ */
+function isDelimiterOnlyOrBlankLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === "") {
         return true;
     }
-    return false;
+    return /^[\s,;\t|]+$/.test(trimmed) && /[,;\t|]/.test(trimmed);
 }
 /**
  * Strip a leading metadata line (e.g. Excel's `sep=;` preamble) from
@@ -737,13 +791,14 @@ export class CSVProcessor {
      * @returns Formatted CSV data ready for LLM (JSON or Markdown)
      */
     static async process(content, options) {
-        const { maxRows: rawMaxRows = 1000, formatStyle = "raw", includeHeaders = true, sampleDataFormat = "json", extension = null, encoding, sanitizeColumnNames = false, columnNameCase = "snake_case", parseTimeoutMs = DEFAULT_CSV_STRING_PARSE_TIMEOUT_MS, } = options || {};
+        const { maxRows: rawMaxRows = 1000, formatStyle = "raw", includeHeaders = true, sampleDataFormat = "json", extension = null, encoding, sanitizeColumnNames = false, columnNameCase = "snake_case", parseTimeoutMs = DEFAULT_CSV_STRING_PARSE_TIMEOUT_MS, skipEmptyLines = true, } = options || {};
         const maxRows = Math.max(1, Math.min(10000, rawMaxRows));
         logger.debug("[CSVProcessor] Starting CSV processing", {
             contentSize: content.length,
             formatStyle,
             maxRows,
             includeHeaders,
+            skipEmptyLines,
         });
         // #362: detect the encoding (BOM → chardet → UTF-8 fallback) or honor the
         // caller's override, instead of the previous hard-coded UTF-8 decode.
@@ -764,7 +819,15 @@ export class CSVProcessor {
             }
             // dataLines already has the metadata line (if any) stripped.
             const csvLines = dataLines;
-            const limitedLines = csvLines.slice(0, 1 + maxRows); // header + data rows
+            const headerLine = csvLines[0] ?? "";
+            const rawDataLines = csvLines.slice(1);
+            // #373: drop blank AND delimiter-only data lines (e.g. `,,`) so raw
+            // content matches structured `isBlankCsvDataRow` semantics.
+            const effectiveDataLines = skipEmptyLines
+                ? rawDataLines.filter((line) => !isBlankCsvRawLine(line, delimiter))
+                : rawDataLines;
+            const limitedDataLines = effectiveDataLines.slice(0, maxRows);
+            const limitedLines = csvLines.length === 0 ? [] : [headerLine, ...limitedDataLines];
             // #378: opt-in — rewrite the literal header line with sanitized,
             // deduped identifiers so the raw CSV text shown to the LLM has clean
             // column names too. (Splits on commas to match the existing raw-branch
@@ -780,12 +843,10 @@ export class CSVProcessor {
             // #1199: quote-aware, delimiter-aware split (matches the
             // sanitizeColumnNames branch above and #1192's detected delimiter).
             const headerFields = splitCSVFields(limitedLines[0] || "", delimiter);
-            const rowCount = limitedLines
-                .slice(1)
-                .filter((line) => line.trim() !== "").length;
-            const originalRowCount = csvLines
-                .slice(1)
-                .filter((line) => line.trim() !== "").length;
+            // When preserving empties, blank lines count as rows; when skipping,
+            // only non-empty data lines do.
+            const rowCount = limitedDataLines.length;
+            const originalRowCount = effectiveDataLines.length;
             const wasTruncated = rowCount < originalRowCount;
             if (wasTruncated) {
                 logger.warn(`[CSVProcessor] CSV data truncated: showing ${rowCount} of ${originalRowCount} rows (limit: ${maxRows})`);
@@ -802,17 +863,16 @@ export class CSVProcessor {
                 truncated: wasTruncated,
             });
             // Parse a sample for enhanced metadata analysis (raw format still
-            // benefits from column analysis). Reuse the already-split, already
-            // metadata-stripped `dataLines` and the already-detected `delimiter`
-            // via the shared streamParse() core instead of routing `limitedCSV`
-            // back through parseCSVStringWithMeta(), which would re-split/re-join
-            // it and re-run a redundant BOM/metadata/delimiter-detection pass.
+            // benefits from column analysis). Feed the already-filtered limited
+            // lines and honor skipEmptyRows so blank/delimiter-only rows do not
+            // consume the sample limit (#373).
             const sampleRows = Math.min(rowCount, 500);
-            const { rows: sampleForAnalysis, timedOut: rawTimedOut } = await this.streamParse(Readable.from([dataLines.slice(0, 1 + sampleRows).join("\n")]), undefined, {
+            const { rows: sampleForAnalysis, timedOut: rawTimedOut } = await this.streamParse(Readable.from([limitedLines.join("\n")]), undefined, {
                 maxRows: sampleRows,
                 skipLines: 0,
                 timeoutMs: parseTimeoutMs,
                 delimiter,
+                skipEmptyRows: skipEmptyLines,
             });
             const { columnMetadata, dataQualityWarnings, dataQualityScore } = analyzeColumns(sampleForAnalysis);
             // Log data quality summary
@@ -856,51 +916,83 @@ export class CSVProcessor {
         // `delimiter`) — reuse both via the shared streamParse() core instead of
         // routing csvString back through parseCSVStringWithMeta(), which would
         // re-split it and re-run metadata/delimiter detection a second time.
-        const { rows, timedOut: structuredTimedOut } = await this.streamParse(Readable.from([dataLines.join("\n")]), undefined, { maxRows, skipLines: 0, timeoutMs: parseTimeoutMs, delimiter });
-        // Filter out empty rows (empty objects or rows with only whitespace values from blank lines)
+        const { rows, timedOut: structuredTimedOut, headers: parsedHeaders, } = await this.streamParse(Readable.from([dataLines.join("\n")]), undefined, {
+            maxRows,
+            skipLines: 0,
+            timeoutMs: parseTimeoutMs,
+            delimiter,
+            // Count only non-blank rows toward maxRows when skipping empties
+            // (#373), so maxRows: 2 still yields two real data rows if blanks
+            // appear first.
+            skipEmptyRows: skipEmptyLines,
+        });
+        // Filter out empty rows (empty objects or rows with only whitespace values
+        // from blank lines). #373: `skipEmptyLines` (default true) controls this;
+        // set false to preserve blank-line rows in structured output.
         const filteredRows = rows.filter((row) => {
             if (!row || typeof row !== "object") {
                 return false;
             }
-            const keys = Object.keys(row);
-            if (keys.length === 0) {
-                return false;
+            if (!skipEmptyLines) {
+                return true;
             }
-            // Check if all values are empty or whitespace-only
-            return !Object.values(row).every((val) => val === "" || (typeof val === "string" && val.trim() === ""));
+            return !isBlankCsvDataRow(row);
         });
+        // Schema must come from parser headers or the first non-blank data row,
+        // never from a preserved leading blank row (#373 review).
+        const schemaRow = filteredRows.find((row) => row && typeof row === "object" && !isBlankCsvDataRow(row));
+        const schemaHeaders = (parsedHeaders && parsedHeaders.length > 0
+            ? [...parsedHeaders]
+            : undefined) ??
+            (schemaRow ? Object.keys(schemaRow) : undefined) ??
+            (filteredRows[0] ? Object.keys(filteredRows[0]) : []) ??
+            [];
         // #378: opt-in — remap each row's keys from original → sanitized identifiers.
+        // Always project onto schemaHeaders first so preserved blank rows still
+        // carry the real column keys for Markdown/JSON (#373 review).
         let structuredColumnNameMapping;
         const sanitizedToOriginal = new Map();
-        let nonEmptyRows = filteredRows;
-        if (sanitizeColumnNames && filteredRows.length > 0) {
-            const origHeaders = Object.keys(filteredRows[0]);
+        let columnNames = schemaHeaders;
+        let nonEmptyRows = schemaHeaders.length === 0
+            ? filteredRows
+            : filteredRows.map((row) => {
+                const out = Object.create(null);
+                for (const h of schemaHeaders) {
+                    out[h] = typeof row[h] === "string" ? row[h] : "";
+                }
+                return out;
+            });
+        if (sanitizeColumnNames && schemaHeaders.length > 0) {
+            const origHeaders = schemaHeaders;
             const { sanitized, mapping } = buildColumnNameMapping(origHeaders, columnNameCase);
             origHeaders.forEach((original, i) => {
                 if (original !== sanitized[i]) {
                     sanitizedToOriginal.set(sanitized[i], original);
                 }
             });
-            nonEmptyRows = filteredRows.map((row) => {
+            nonEmptyRows = nonEmptyRows.map((row) => {
                 // Defense-in-depth: a null-prototype target means an attacker-chosen
                 // header literally named "__proto__"/"constructor"/"prototype" can
                 // only ever create a harmless own property, never touch
                 // Object.prototype (#1199).
                 const out = Object.create(null);
                 origHeaders.forEach((h, i) => {
-                    out[sanitized[i]] = row[h];
+                    out[sanitized[i]] = row[h] ?? "";
                 });
                 return out;
             });
             structuredColumnNameMapping = mapping.length > 0 ? mapping : undefined;
+            columnNames = sanitized;
         }
         // Extract metadata from parsed results
         const rowCount = nonEmptyRows.length;
-        const columnNames = nonEmptyRows.length > 0 ? Object.keys(nonEmptyRows[0]) : [];
         const columnCount = columnNames.length;
         const hasEmptyColumns = columnNames.some((col) => !col || col.trim() === "");
-        const sampleRows = nonEmptyRows.slice(0, 3);
-        const sampleData = this.formatSampleData(sampleRows, sampleDataFormat, includeHeaders);
+        // Sample / analysis should prefer non-blank rows so a preserved leading
+        // blank does not poison type detection or formatSampleData.
+        const rowsForAnalysis = nonEmptyRows.filter((row) => !isBlankCsvDataRow(row));
+        const sampleRows = (rowsForAnalysis.length > 0 ? rowsForAnalysis : nonEmptyRows).slice(0, 3);
+        const sampleData = this.formatSampleData(sampleRows, sampleDataFormat, includeHeaders, columnNames);
         if (hasEmptyColumns) {
             logger.warn("[CSVProcessor] CSV contains empty or blank column headers", {
                 columnNames,
@@ -909,8 +1001,9 @@ export class CSVProcessor {
         if (rowCount === 0) {
             logger.warn("[CSVProcessor] CSV file contains no data rows");
         }
-        // Perform enhanced column analysis
-        const { columnMetadata, dataQualityWarnings, dataQualityScore } = analyzeColumns(nonEmptyRows);
+        // Perform enhanced column analysis on non-blank rows so preserved
+        // leading blanks do not yield an empty schema (#373 review).
+        const { columnMetadata, dataQualityWarnings, dataQualityScore } = analyzeColumns(rowsForAnalysis.length > 0 ? rowsForAnalysis : nonEmptyRows);
         // #378: carry the pre-sanitization header on each renamed column.
         if (sanitizedToOriginal.size > 0) {
             for (const col of columnMetadata) {
@@ -929,7 +1022,7 @@ export class CSVProcessor {
         }
         // Format parsed data
         logger.debug(`[CSVProcessor] Converting ${rowCount} rows to ${formatStyle} format`);
-        const formatted = this.formatForLLM(nonEmptyRows, formatStyle, includeHeaders);
+        const formatted = this.formatForLLM(nonEmptyRows, formatStyle, includeHeaders, columnNames);
         logger.info("[CSVProcessor] ✅ Processed CSV file", {
             formatStyle,
             rowCount,
@@ -954,7 +1047,7 @@ export class CSVProcessor {
                 columnMetadata,
                 dataQualityWarnings,
                 dataQualityScore,
-                hasHeaders: detectHasHeaders(columnNames, nonEmptyRows),
+                hasHeaders: detectHasHeaders(columnNames, rowsForAnalysis.length > 0 ? rowsForAnalysis : nonEmptyRows),
                 detectedDelimiter: delimiter,
                 detectedEncoding,
                 encodingConfidence,
@@ -1240,7 +1333,7 @@ export class CSVProcessor {
                 finish(() => {
                     logger.warn(`[CSVProcessor] Parse timed out after ${Date.now() - startTime}ms with ${rows.length} partial row(s)`);
                     abort();
-                    resolve({ rows, timedOut: true });
+                    resolve({ rows, timedOut: true, headers: capturedHeaders });
                 });
             }, opts.timeoutMs);
             if (typeof timer.unref === "function") {
@@ -1277,6 +1370,10 @@ export class CSVProcessor {
                     });
                     return;
                 }
+                // #373: blank rows must not consume maxRows when skipping empties.
+                if (opts.skipEmptyRows && isBlankCsvDataRow(row)) {
+                    return;
+                }
                 lastRowColumnCount = Object.keys(row).length;
                 rows.push(row);
                 count++;
@@ -1284,14 +1381,14 @@ export class CSVProcessor {
                     logger.debug(`[CSVProcessor] Reached row limit ${opts.maxRows}, stopping parse`);
                     finish(() => {
                         abort();
-                        resolve({ rows, timedOut: false });
+                        resolve({ rows, timedOut: false, headers: capturedHeaders });
                     });
                 }
             })
                 .on("end", () => {
                 finish(() => {
                     logger.debug(`[CSVProcessor] Parsing complete: ${rows.length} rows parsed`);
-                    resolve({ rows, timedOut: false });
+                    resolve({ rows, timedOut: false, headers: capturedHeaders });
                 });
             })
                 .on("error", (error) => {
@@ -1315,25 +1412,36 @@ export class CSVProcessor {
     /**
      * Format parsed CSV data for LLM consumption
      * Only used for JSON and Markdown formats (raw format handled separately)
+     *
+     * @param columnNames - Optional schema headers (#373). When preserved blank
+     *   rows lead `rows`, Markdown must still use the real column names.
      */
-    static formatForLLM(rows, formatStyle, includeHeaders) {
+    static formatForLLM(rows, formatStyle, includeHeaders, columnNames) {
         if (rows.length === 0) {
             return "CSV file is empty or contains no data.";
         }
         if (formatStyle === "json") {
             return JSON.stringify(rows, null, 2);
         }
-        return this.toMarkdownTable(rows, includeHeaders);
+        return this.toMarkdownTable(rows, includeHeaders, columnNames);
     }
     /**
      * Format as markdown table
      * Best for small datasets (<100 rows)
+     *
+     * @param columnNames - Optional explicit headers (#373). Falls back to
+     *   `Object.keys(rows[0])` when omitted.
      */
-    static toMarkdownTable(rows, includeHeaders) {
+    static toMarkdownTable(rows, includeHeaders, columnNames) {
         if (rows.length === 0) {
             return "CSV file is empty or contains no data.";
         }
-        const headers = Object.keys(rows[0]);
+        const headers = columnNames && columnNames.length > 0
+            ? columnNames
+            : Object.keys(rows[0] ?? {});
+        if (headers.length === 0) {
+            return "CSV file is empty or contains no data.";
+        }
         // Escape backslashes, pipes, and sanitize newlines to keep rows intact
         const escapePipe = (str) => str
             .replace(/\\/g, "\\\\")
@@ -1358,9 +1466,10 @@ export class CSVProcessor {
      * @param sampleRows - Array of sample row objects
      * @param format - Output format for sample data
      * @param includeHeaders - Whether to include headers in CSV/markdown formats
+     * @param columnNames - Optional schema headers for csv/markdown (#373)
      * @returns Formatted sample data as string or array
      */
-    static formatSampleData(sampleRows, format, includeHeaders) {
+    static formatSampleData(sampleRows, format, includeHeaders, columnNames) {
         if (sampleRows.length === 0) {
             return format === "object" ? [] : "No data rows";
         }
@@ -1370,9 +1479,9 @@ export class CSVProcessor {
             case "json":
                 return JSON.stringify(sampleRows, null, 2);
             case "csv":
-                return this.toCSVString(sampleRows, includeHeaders);
+                return this.toCSVString(sampleRows, includeHeaders, columnNames);
             case "markdown":
-                return this.toMarkdownTable(sampleRows, includeHeaders);
+                return this.toMarkdownTable(sampleRows, includeHeaders, columnNames);
             default:
                 return sampleRows;
         }
@@ -1382,13 +1491,19 @@ export class CSVProcessor {
      *
      * @param rows - Array of row objects
      * @param includeHeaders - Whether to include header row
+     * @param columnNames - Optional explicit headers (#373)
      * @returns CSV formatted string
      */
-    static toCSVString(rows, includeHeaders) {
+    static toCSVString(rows, includeHeaders, columnNames) {
         if (rows.length === 0) {
             return "";
         }
-        const headers = Object.keys(rows[0]);
+        const headers = columnNames && columnNames.length > 0
+            ? columnNames
+            : Object.keys(rows[0] ?? {});
+        if (headers.length === 0) {
+            return "";
+        }
         // Escape CSV values (wrap in quotes if contains comma, quote, or newline)
         const escapeCSV = (value) => {
             if (value.includes(",") ||

package/dist/lib/voice/providers/OpenAITTS.d.ts

@@ -30,8 +30,14 @@ export declare class OpenAITTS implements TTSHandler {
     synthesize(text: string, options?: TTSOptions): Promise<TTSResult>;
     /**
      * Map TTSAudioFormat to OpenAI response_format.
-     * OpenAI TTS supports: mp3, wav, opus (ogg maps to opus).
-     * Unsupported formats are coerced to mp3 with a warning.
+     *
+     * OpenAI's /audio/speech accepts mp3, opus, aac, flac, wav and pcm. This map
+     * previously stopped at mp3/wav/ogg/opus/pcm16, so `flac` — a valid
+     * TTSAudioFormat *and* a real OpenAI response_format — was treated as
+     * unsupported and silently downgraded to mp3 (#479). A caller who asked for
+     * lossless got lossy, and the only signal was a warn-level log.
+     *
+     * Formats OpenAI genuinely cannot produce still coerce to mp3 with a warning.
      */
     private mapFormat;
     /**