Sixteen ways the SNT→EDF exporter could break (and the property that catches each)

[Plantucha]

None of these are bugs today. Every one is a one-line slip that would
compile, would not crash, and would produce an EDF file that opens — while
being wrong in a way a user would eventually notice in OSCAR. This is a list
of failure modes and the property that distinguishes each one, not a list of
defects.

It exists because the exporter's rules are currently implicit: they live in
the control flow of edf_gen.c and in whoever last read it. One of them has
already been broken in a shipped release — #189, where SNT v2 missing samples
reached SA2.edf as digital 0 and showed up as real zeros — so the list is
not hypothetical about the class, only about the instances.

Where a row says AS11-verified, the property was checked against a real
AirSense 11 SD card (233 day folders, 292 sessions, 1478 EDF files). The rest
are derived from the EDF format or from edf_gen.c's own stated intent, and
are marked reasoned.

---

Missing data

The AS11 marks an unavailable sample with -1 in the EDF. Getting that wrong
does not look like an error; it looks like a patient whose pulse was 0.

one-line slip	what a user sees	property that catches it
the reader returns the v1 sentinel regardless of file version	in a v2 file INT16_MIN is not recognised as missing, so it is scaled and clamped like real data — gaps become extreme values	the same night stored as SNT v1 and as v2 must export byte-identical EDF — AS11-verified (-1 is the marker in 1478/1478 files)
the sentinel stops bypassing the physical→digital scaling	-1 goes through the scale and lands on some other number; missing data reads as a measurement	a stored sentinel reaches SA2.edf as -1 — AS11-verified
missing written as 0 instead of -1	OSCAR shows 0 bpm and 0 % as genuine readings — this is exactly what #189 did	as above — AS11-verified
the summary path drops its -1 guard before dividing by the logical scale	the summary channel's gaps become 0 after the division	spool_to_edf() returns -1 unchanged for a sentinel input — reasoned

File length and record count

An EDF header states the record count before any data is written, so a count
that disagrees with the bytes on disk produces a file readers cannot parse.
The failure mode is a crash-interrupted night, which is the common case.

one-line slip	what a user sees	property that catches it
the header's sample_count is trusted over the measured file length	after a crash the header promises records the file does not contain; the night fails to load	the count is clamped to what is on disk, so size == header + records × record — AS11-verified (holds in 1478/1478)
the record count is written one too high	the last record is promised and never written; readers hit EOF mid-record	as above — AS11-verified
the measured file length is off by one byte	a file torn mid-sample rounds up, counting a partial frame as a whole one	119 whole frames plus 3 stray bytes still exports one record, not two — reasoned

Gating and the session window

The .snt files capture from therapy start, but BRP/PLD/SA2 must begin at the
gating signal (_ZLE rising, else MaskOn) and end at mask-off. Both edges are
easy to get subtly wrong, and the result is a night that is silently shifted
or padded rather than obviously broken.

one-line slip	what a user sees	property that catches it
the mask-off limit is compared the wrong way round	the export runs past mask-off and the night is padded with whatever the sensors did afterwards	a 60 s mask-on window produces exactly one record — reasoned
the AS11→NTP clock drift is subtracted instead of added	every gated stream starts on the wrong second, off by twice the drift	a gated export equals the same night exported ungated, shifted by the skip — reasoned
the rising-edge scan no longer stops at the first match	on a night with several mask on/off cycles the data starts from the last rising edge, discarding most of it	the first rising edge starts the export, on a night containing rise/fall/rise — reasoned

Day labelling

A DATALOG day starts at noon, not midnight, so an after-midnight session
belongs to the previous folder. Two independent implementations of this exist
— noon_day_folder() in edf_gen.c and as11_time_noon_day() — which is
what makes it checkable without pinning any expected value.

one-line slip	what a user sees	property that catches it
the noon comparison becomes inclusive on either side	a session starting at 12:00–12:59 is filed under the previous day; the night appears on the wrong date	noon starts the new day, checked at 11:59:59 / 12:00:00 — AS11-verified (40 of 292 real sessions are filed under the previous day)
the same slip on the AS11 side	the two day-labellers disagree and the folder no longer matches the session	the two must agree for the same instant, swept every 30 min across a year — reasoned
the session's own UTC offset is dropped in favour of the device's timezone	a night recorded in another timezone, or with the device clock unset, lands on the wrong day (the class of #183)	the session offset decides the day, not the device zone — reasoned
the offset-present check is inverted	the offset is used only when it is absent — the two branches swap	as above — reasoned

Channels and range

one-line slip	what a user sees	property that catches it
the overflow clamp saturates to the negative end	a sensor spike exports as maximal negative flow: a large inspiration reads as a large expiration	an overflowing sample saturates at the dig_max the header itself declares — AS11-verified (the machine declares dig[-1000,1500] for flow, not full int16)
the channel-map bound check is loosened by one	the exporter reads one channel past the end of every PLD frame — out of bounds, and a garbage channel	a PLD .snt with fewer channels than its map indexes is refused, not exported — reasoned

---

Three that look like bugs and are not

Worth writing down so they are not "fixed" twice:

• channels_in_file <= 0 → < 0. Looks like a division-by-zero waiting
  to happen. A zero-channel file is refused by the channel-count and
  channel-map checks before it reaches that arithmetic.
• end <= sizeof(header) → <. For a file that is exactly a header, the
  fall-through computes 0 / frame, which is the same 0 the early return
  gives.
• memset(hdr, ' ') → memset(hdr, 0). The EDF spec wants space padding,
  but every one of the 256 fixed-header bytes is subsequently overwritten by a
  space-padded field, so the fill value never reaches the file.

What is not covered here

The list is about the reader — edf_gen.c. The SNT writer
(session_writer.c) is where #189 actually originated, and none of these
properties would have caught it at the point it was written; they catch it one
stage later, when the wrong bytes are read back. A writer→reader round trip is
the gap.

[ilyakruchinin]

Hi @Plantucha,

Thank you for this incredible audit and taxonomy of failure modes. The distinction you drew between empirical ground truth (validated against 1,478 real AirSense 11 files) and reasoned specification constraints is methodologically top-tier.

Every single one of the 16 "one-line slips" you identified has been audited, validated, and hardened in our codebase. Furthermore, we implemented a dedicated host property test suite (scripts/edf_properties_test.c, 37 assertions) and a writer–reader round-trip contract test (scripts/roundtrip_contract_test.py) that permanently guards against all 16 regressions.

Here is how each failure mode and architectural observation was resolved:

---

Category 1: Missing Data Sentinels (Slips 1–4)

• Slip 1 — Reader returns v1 sentinel regardless of file version:
  • Mitigation: Centralized format logic into snt_format.h. The helper snt_missing_for(uint8_t version) returns SNT_MISSING_V1 (-1) for v1 and SNT_MISSING_V2 (INT16_MIN / -32768) for v2+. Tested with dual fixtures asserting byte-identical EDF output across both versions.
• Slip 2 — Sentinel stops bypassing physical→digital scaling:
  • Mitigation: Declarative signal definitions in edf_data_dict.h track invalid_passthrough. In edf_waveform.c, if sig->invalid_passthrough && stored == missing_sentinel, the pipeline immediately writes digital -1 (0xFFFF) without entering linear transformation.
• Slip 3 — Missing written as 0 instead of -1 (Issue fix(session_writer): write the v2 missing-data sentinel for absent SA2/PLD samples #189):
  • Mitigation: Fixed at the writer layer (session_writer.c), and reinforced by roundtrip_contract_test.py. The test runs actual stream generation with synthetic dropouts and asserts that SA2.edf digital records contain 0xFFFF rather than 0x0000.
• Slip 4 — Summary drops -1 guard before dividing by logical scale:
  • Mitigation: In edf_summary.c, spool_to_edf(int16_t raw, int num, int den) explicitly checks if (raw == -1 || den <= 0) return -1; before scaling, preventing absent AHI/SpO2/Leak summary metrics from collapsing to 0 or -5.

---

Category 2: File Length & Record Count (Slips 5–7)

• Slip 5 — Header sample_count trusted over measured file length:
  • Mitigation: snt_available_samples() inspects the physical file size via fseek/ftell (or stat), subtracts the 28-byte header, and calculates whole available frames. The effective count is clamped to min(hdr.sample_count, available_samples), protecting against crash/power-cut truncations.
• Slip 6 — Record count written one too high:
  • Mitigation: The EDF header record count is computed via strict integer floor division (int)(total_samples / samples_per_record). Trailing fractional records are never declared.
• Slip 7 — Measured file length off by one byte:
  • Mitigation: Frame arithmetic (file_bytes - sizeof(snt_header_t)) / (channels * sizeof(int16_t)) safely discards incomplete trailing byte fragments left by mid-write power interruptions.

---

Category 3: Gating & Session Window (Slips 8–10)

• Slip 8 — Mask-off limit compared the wrong way round:
  • Mitigation: Verified condition if (max_samples > 0 && max_samples < total_samples) total_samples = max_samples;. Gating strictly trims the post-therapy blower ramp-down window (50–60 s) to match AS11 SD card parity.
• Slip 9 — AS11→NTP clock drift subtracted instead of added:
  • Mitigation: Preserved the canonical sign convention: T_ntp = T_as11 + drift. Verified in as11_time_test.c across event parsing and gating windows.
• Slip 10 — Rising-edge scan no longer stops at first match:
  • Mitigation: In edf_find_zle_edge_time(), rising edge detection (want_value == 1) returns on the first match encountered. Furthermore, we fixed an existing flaw where find_zle_edge_time() only inspected array index 0: it now iterates through the entire JSON-RPC events array identically to find_mask_on/off_time().

---

Category 4: Day Labelling & Timezone Mechanics (Slips 11–14)

• Slip 11 — Noon comparison becomes inclusive on either side:
  • Mitigation: Enforced strict < 12 / < 43200 boundary in as11_time_noon_day(). Verified against 292 empirical AS11 sessions: 11:59:59 maps to day D-1; 12:00:00 maps to day D.
• Slip 12 — Divergence between duplicate noon-day implementations:
  • Mitigation: Eliminated noon_day_folder() completely. During planning, we discovered three separate places in edf_gen.c calculating noon shifts using local localtime_r(). All three sites (the DATALOG/YYYYMMDD folder, the STR.edf header start_date, and the recording_id) now uniformly derive from as11_time_noon_day(start_epoch_ms - clock_drift_ms).
• Slip 13 & 14 — UTC offset dropped or offset-present check inverted:
  • Mitigation: Empirical testing with the AS11 BLE RPC proxy confirmed that the physical machine names its DATALOG/YYYYMMDD folders strictly according to its internal TimeZoneFeature.TimeZoneOffset, regardless of host wall-clock time. as11_time_init_from_settings() anchors the authoritative offset; fallback to ESP local time occurs only if the offset is completely missing.

---

Category 5: Channels & Numerical Ranges (Slips 15–16)

• Slip 15 — Overflow clamp saturates to negative end:
  • Mitigation: Implemented clamp_i16(int32_t val, int16_t min, int16_t max) with independent directional clamping and 64-bit calculation headroom, preventing positive inspiratory spikes from wrapping to negative expiratory bounds.
• Slip 16 — Channel-map bound check loosened by one:
  • Mitigation: Hardened via is_channel_map_valid(), which strictly enforces map[i] >= 0 && map[i] < snt_channels. Tested with negative and boundary indices in edf_properties_test.c.

---

The Three "Non-Bugs"

We audited all three code patterns you highlighted:

1. channels_in_file <= 0: Harmless because calling code validates snt_channels > 0 before invocation.
2. end <= sizeof(header): Harmless because (end - sizeof(hdr)) / frame yields 0 frames for exact-header files either way.
3. memset(hdr, ' '): Harmless because every single byte of the 256-byte header is overwritten by strictly bounded, space-padded ASCII field formatters.

---

Additional Improvements & Architecture Evolution

1. Symmetric Rounding in spool_to_edf():
   Addressing integer truncation toward zero, we updated spool_to_edf() to use unbiased half-up/half-down integer rounding:
   int32_t half = den / 2; int32_t rounded = (prod >= 0) ? (prod + half) / den : (prod - half) / den;

2. Closing the Writer–Reader Contract Gap:
   scripts/roundtrip_contract_test.py generates synthetic multi-channel SNT files, processes them through the EDF conversion pipeline, and inspects the resulting EDF headers and byte streams to ensure full end-to-end fidelity.

3. Modular Exporter Decomposition:
   We decomposed the monolithic ~4,700-line edf_gen.c into modular, single-responsibility components:

   • snt_format.h / edf_data_dict.h: Unified 28-byte SNT binary header and declarative signal definitions.
   • edf_header.c: EDF 256-byte header writer, CCITT CRC16, IEEE CRC32, and Identification files.
   • edf_waveform.c: Waveform streaming, gating, de-interleaving, and scaling.
   • edf_annotations.c: EVE.edf and CSL.edf TAL list generator.
   • edf_summary.c: Protobuf wire decoder and cumulative multi-day STR.edf aggregation.
   • edf_gen.c: Clean ~1,000-line orchestrator handling directory structures, SD storage leases, and transactional single-day rebuilds.

Huge thanks again for the incredible collaboration and insight!

The updated codebase is now being tested internally. I will release it once testing is successful.