Technical design
Methodology and safety boundaries
The implementation favors data provenance, minimal mutation, explicit uncertainty, and repeatable verification over convenience-only conversion.
1. Input identification
The parser does not rely exclusively on the filename. It checks ZIP, OLE, JSON, XML, and text signatures, then inspects package members where applicable. Path normalization rejects absolute paths, backslashes, traversal components, duplicate normalized names, encryption, unsupported compression, multi-disk archives, ZIP64, excessive entry counts, excessive expanded size, and suspicious compression ratios.
2. Redundant reading
Delimited text
A byte-oriented state machine records each field’s raw value span while respecting quoted delimiters, escaped quotes, and embedded line endings. A separate decoded-string state machine parses the same input. Their matrices are compared before byte-preserving output is allowed.
OOXML
The package reader resolves workbook and worksheet relationships, shared strings, styles, date systems, and content inventories. Each selected worksheet is parsed once through browser XML DOM APIs and again through a raw XML cell-span scanner. Values, formula text, and storage types are reconciled.
3. Gene-symbol matching
Reference records are indexed by approved symbol, previous symbols, aliases, and stable identifiers. Matching is classified rather than flattened into a single replacement:
- approved exact match;
- approved symbol with capitalization difference;
- unique or ambiguous previous-symbol match;
- unique or ambiguous alias match;
- unique or ambiguous date-recovery match;
- unmatched input.
Only unambiguous supported mappings are eligible for a default recommendation. Alias mappings are disabled by default because aliases often have weaker semantics than previous symbols.
4. Excel-risk classification
The protection rules operate on the original string rather than a JavaScript number whenever possible. They detect leading zeroes, long integers, scientific notation patterns, month/date/time forms, formula prefixes, problematic comma placement, boundary whitespace, quote patterns, control characters, and the legacy Excel formula-length limit.
5. Output paths
| Source | Preferred writer | Verification |
|---|---|---|
| UTF-8 CSV/TSV/TXT | Raw byte-span replacement for approved fields | Reader agreement and unchanged bytes outside patch spans |
| XLSX/XLSM | Worksheet XML cell replacement inside the existing package | Reopen output, confirm changed cells, compare every unmodified uncompressed package part, and compare macro bytes |
| JSON/ODS or non-byte-preservable text | New minimal XLSX using explicit text and conservative numeric cells | Package read-back and change manifest; labeled as conversion rather than source preservation |
| Scan only | No data output | Audit package with inventory, findings, warnings, and reconciliation metadata |
6. Blocked or constrained cases
- Encrypted ZIP/OOXML files are blocked.
- Signed OOXML workbooks may be inspected but are not modified.
- Formula cells are not automatically replaced.
- Legacy OLE XLS files require conversion in a trusted spreadsheet application before processing.
- Unsupported XML encodings and malformed relationships fail closed.
- Only the selected worksheet is exported for matrix-based formats in this initial static release.
- The default HGNC reference is deliberately compact; broad symbol migration should use a complete locally loaded HGNC file.
7. Reproducibility artifacts
The audit ZIP includes a machine-readable JSON manifest, CSV and JSON change sets, warnings, and the primary output when one exists. The manifest records the input hash, output hash, application version, workflow, reference version, reader names, reconciliation state, change counts, unresolved ambiguity count, and verification result.