Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions docs/adr/ADR-420-managed-source-aware-room-learner.md
Original file line number Diff line number Diff line change
Expand Up @@ -428,3 +428,52 @@ replaced. Existing recovery descriptor/checkpoint versions and expiry semantics
unchanged. This is proposed source work, not protection of a currently running
older helper: installing it would require stopping that helper, so live volatile
cohorts must not be sacrificed to obtain this capability.


## November 11, 2026: proposed variable-source receiver profile

Dragan requested that the room learner retain every configured source rather than
requiring exactly three. The local candidate adds the explicitly versioned
`native-2s-variable-source-56bin-receiver20-operator-eight-step-v2` profile. Earlier
three-source profiles, schedule hashes, recovery data and key derivations remain
unchanged. This amendment describes an engineering candidate, not physical
qualification or a change to the default operating detector.

The candidate supports 2–8 source-bound views of 56 canonical features (C5 keeps
its 53 native IQ positions before the existing projection) and retains the existing
eight operator episodes: 64 training windows and 16 reserved check windows.
Resource preflight remains below two million numeric values and a 64 MiB
serialized-checkpoint estimate. Every source participates in every accepted
window; adding/removing a source changes context/model identity and requires a
new run. No source is silently removed or padded. Recovery has a separate
account/installation-bound encryption purpose and directory; pending older
recovery stays discoverable under its original profile.

The receiver policy is explicitly distinct from a sensor measurement clock.
The November 10 executed metadata-only C5 read-loop sample reported means of
20.42–20.62 packets/s, minimum observed intervals of 7.7–20.8 microseconds and
maximum gaps of 131–137 milliseconds. It did not distinguish radio delivery
from host scheduling, establish source measurement time, or qualify sensing.
An instantaneous inverse arrival interval therefore cannot establish a
20 Hz sensor sample rate.

`Arrival18To22Burst200MsV1` retains every admitted retained-window frame identity
and receiver timestamp with its existing canonical feature values; the native-to-feature
projection is unchanged. It bounds observed window and whole-period rates
to 18–22 packets/s. Whole-period rate is checked only at the completed episode
frontier/seal, summing each positive resumed part’s packet intervals and receiver
span while excluding paused gaps; partial durable prefixes keep structural,
sequence, gap and retained-window checks without an aggregate-rate veto. It bounds
maximum gaps to 200 ms, and requires strictly increasing receiver timestamps.
Native windows retain a two-second target, at most 2.2 seconds observed span,
200 ms first-arrival/skew bounds and at most 52 rows per source. There is no
synthetic clock, temporal resampling to hide a gap, dropping within admitted retained windows, or source-clock /
phase / accuracy claim. Excess density, long gaps, missing sources, duplicates
and changed input/context still reject. Older interval-strict profiles keep
their exact original rules.

Synthetic checks exercise source-count bounds, bursty four-C5 native input,
rejected gaps/floods, whole four-source training with reserved checks excluded,
model export/import identity, durable genesis and recovery isolation. Physical
four-C5 capture, independent checks, qualification, explicit selection and Room
Save remain required before describing this installation as qualified.
118 changes: 118 additions & 0 deletions docs/validation/2026-11-10-c5-native-lltf8-contract.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# Managed C5 L-LTF8 format contract v1

This software contract does not qualify hardware, sensing accuracy or phase.
The existing C5 producer zero-initializes `lltf_bit_mode`; ESP-IDF6.0.2 defines
that as12-bit components. An old106-byte callback is therefore not evidence
of53 signed-int8 complex samples. Bare53-slot ADR-018 input stays rejected.

Primary references: [SDKv6.0.2 CSI fields](https://github.com/espressif/esp-idf/blob/v6.0.2/components/esp_wifi/include/esp_wifi_he_types.h),
[SDKvendor features](https://github.com/espressif/esp-idf/blob/v6.0.2/docs/en/api-guides/wifi-driver/wifi-vendor-features.rst),
and [Espressif packing clarification](https://github.com/espressif/esp-idf/issues/18982#issuecomment-5420118269).

## Producer claim and exact wire extent

The separate local producer opts into8-bit legacy/forcedL-LTF only and checks
actual CSI-format fields/zero scaling through SDK configuration readback.
STA bandwidth is explicitly set and read back as20MHz; it is a configured
interface/acquisition constraint, not a measurement of full PPDU occupied
bandwidth. Only original non-HT OFDMBB1 (11g/11a), secondary-none,
valid-estimate and106-byte callbacks carry this format claim. Other
metadata is withheld and reported without raw samples. The producer and its
physical callback packing/shape must be validated on one board before
managed capture is attempted; a software test or marker alone is not that
validation. The claim does not raise the existing provenance/trust grade.

A valid datagram has20bytesADR-018 header +106bytesdeclaredIQ +16bytesexact
suffix. The suffix fields are: ASCII C5L8; version1; componentbits8;
SDK-documented imaginary/real byte-order ID1; LLTF53tone-order ID1;
matched-format-readback1; originalBB1; originalsecondary0; STAbandwidth
readback20MHz; originalestimate-valid1; first-word-invalid0/1;
originalbyte-count106little-endian. Unsupported version, order, packing,
readback, PHY, length, flag or trailing byte is refused before readiness.
The first-word flag must agree with ADR-018 bit5 and with the actual zeroed
four-byte prefix. No HE-invalid flag reinterpretation occurs; HE/HT/VHT and
unproven variants are outside this new profile. Existing64/256 paths retain
their old grid IDs, complex-component convention and magnitude mathematics.

Newv1 only admits IEEE20MHz5GHz primary channels36–64 (step4),100–144
(step4, including112),149–177 (step4). This is a bounded format/channel set,
not physical qualification of every channel or regulatory authorization.
The local firmware driver/AP remains responsible for lawful association.
2.4/6GHz and off-grid5MHz values are not silently broadened into this profile.

## Native representation and fixed derived features

Original received IQ bytes are retained privately/losslessly; native shape
remains[1,53,1]. The explicit SDK-documented signed-int8 imaginary/real
interpretation uses complexre=byte1,im=byte0 for this new format only.
Raw phase remains unqualified and is not consumed. Native carrier indices
remain `[0..26,-26..-1]`; they are stored explicitly, not represented as53
uniform FFT bins or padded into64. DC slot0 is always invalid; SDK's invalid
first four bytes additionally invalidate slot1. No slots are deleted or
renumbered, and sanitized wire bytes stay as received.

The derived amplitude-only feature recipe is intentionally conservative:
exclude native positions0and1 on every packet, then pass those51magnitudes
in original SDK order through the existing length-only56feature resampler.
The discontinuity from+26to-26 is not a uniform physical-frequency axis.
This interpolation creates features, not additional measured carriers;
there is no gain/DC normalization or invented padded IQ. Its separate ID is
`ant1-bins53-ppdu0-c5lltf8-keep53-drop2-linear-v3`. Existing64/256v2IDs and
fixtures remain unchanged. The validated claim binds the original header's
node, sequence and frequency to the canonicalizer input. Per-source cache
keys bind format, native grid, PPDU, frequency and bandwidth; normal existing
freshness/cadence/room/model/selection gates remain authoritative.

## Read-only rejection diagnostics

Only an explicit read-only `include_native_diagnostics=1` query on the
existing room-learner status adds `native_source_diagnostics` (with or
without its existing temporal schema query). Default status, `=0` and mutation
ACKs omit that key entirely, preserving older clients' exact-key schemas.
Values other than0/1 are refused; authorization and mutation semantics are
unchanged. A newer client may fall back once to ordinary status on an older
helper's unsupported-query400/422, never on authentication or parse failure.
The optional field is
for the last rejected packet, never a source-ready or admission verdict.
Storage is bounded by256u8nodeIDs; replies cap32fresh records, prioritize
selected sources, expose total/truncation and expire by receiver-monotonic
age after5seconds. Reasons are static whitelist strings; no IQ, amplitudes,
absolute timestamps or credentials are stored or returned. A rare bad
packet cannot evict/invalidate an otherwise ready cohort, while normal
exact source/grid/frequency withdrawal rules are unchanged. Old app readers
may ignore this new optional status field.

## Verification boundary

Synthetic regressions cover exact decoder metadata mutants, lossless native
bytes/order/masks, no unclaimed53admission, original64/256 behavior,
three independent20/21/22sources through actual UDP parser and ingress,
malformed/unsupportedPHY refusal, changedfrequency/grid/model bindings,
and bounded diagnostic expiry/privacy. Physical source/callback and the
separate producer commit/artifact receipts must be recorded independently.
No source changes are applied to the frozen server#2513b8review branch.

## Existing ADR-018 advisory sync metadata

The first metadata-only Node23 wire probe observed290 packets, all142bytes,
53slots, PPDU0,5240MHz, with the exact C5L8/v1 suffix and header flag0x10.
The strict8930 decoder rejected this known flag. The producer serializer sets
bit4 when its ESP-NOW or802.15.4 cross-node synchronization helper reports valid;
the historical host field name is `ieee802154_sync_valid`. This bit does not
select IQ packing, bandwidth, sanitation or calibrated timing.

The corrected C5 decoder accepts exactly flags0x00/0x10/0x20/0x30, with0x20
still required to agree with suffix sanitation and zeroed prefix bytes. All
other flag bits reject. The complete parsed flag metadata is bound to the
validated token and retained in the private canonical packet. Flipping sync
between the validated header and canonicalization input rejects. The bit does
not change grid/projection/IQ/masks, receiver-only clock, unknown source sample
rate, gain/phase qualification, capture authority or provenance.

`tests/fixtures/c5-node23-wire-metadata-20261110.json` contains the actual
metadata-only receipt and no IQ. The corresponding native test combines those
observed header/suffix facts with explicitly **synthetic IQ**, not a captured
wire replay. Exhaustive256-byte flag controls and real ingress/readiness
regressions are synthetic contract evidence; physical admission requires a
new wire probe against the corrected helper. Legacy64/256 math and IDs stay
unchanged. No firmware change is required for this existing metadata bit.
34 changes: 29 additions & 5 deletions scripts/ci/temporal_test_profiles.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
C2 = PREFIX + 'tests::c2_all_seven_train_phases_use_actual_async_runtime_and_durable_seals_without_fit'
# Exact C4C declaration; the author must verify this name in the actual Rust registry.
C4C = PREFIX + 'public_workflow::acceptance::c4c_default48_public_operator_workflow_native128_and_cold_selection'
VARIABLE_RETRY = PREFIX + 'tests::variable_retry_after_actual_window_cadence_failure_keeps_sixteen_windows_and_seal'
BUDGET = [PREFIX + 'tests::legacy_329_actual_runtime_saturation_retires_and_explicit_fresh_train_chains_343', PREFIX + 'tests::fresh_343_actual_runtime_all_128_gaps_seven_terminal_pauses_and_retirement_fit_budget']
# This initial policy is populated below from reviewed source call sites.
C3 = ['room_learner::lifecycle::temporal_control::fit_control::tests::c3_actual_native_train_fit_and_same_store_cold_report_keep_whole_model_diagnostic',
Expand Down Expand Up @@ -44,6 +45,7 @@ def policy(root):
if not c_marker.is_file():
raise ValueError('C4C acceptance source marker is required; missing source is not coverage')
components += [('C4C', c_marker, [C4C], [(C4C, True, 1)])]
components += [('variableRetry', source / 'lifecycle_temporal_tests.rs', [VARIABLE_RETRY], [(VARIABLE_RETRY, True, 1)])]
active = [item for item in components if item[1].is_file()]
if not active or active[0][0] != 'C2':
raise ValueError('C2 classification/source must exist; zero selected tests is not coverage')
Expand Down Expand Up @@ -147,6 +149,29 @@ def compile_binary(root, release):
raise ValueError('Cargo lib-test compilation failed with exit ' + str(result.returncode))
return validate_cargo_artifacts(root, metadata, artifacts, release)

def execute_batch(command, cwd, log_path):
"""Forward progress immediately and keep the same output for count checks."""
with log_path.open('w', encoding='utf-8') as log:
process = subprocess.Popen(command, cwd=cwd, stdout=subprocess.PIPE,
stderr=subprocess.STDOUT, text=True, bufsize=1)
try:
for line in process.stdout:
log.write(line)
log.flush()
sys.stdout.write(line)
sys.stdout.flush()
return process.wait()
finally:
# A failed log/console sink must not strand the verified child.
if process.poll() is None:
process.terminate()
try:
process.wait(timeout=5)
except subprocess.TimeoutExpired:
process.kill()
process.wait()
process.stdout.close()

def main():
parser = argparse.ArgumentParser()
parser.add_argument('mode', choices=['debug-check', 'release-run'])
Expand Down Expand Up @@ -182,12 +207,11 @@ def main():
for index, batch in enumerate(batches):
verify_selected_executable(selected, binary_sha256)
command = [str(binary), batch['selector'], '--nocapture', '--test-threads=1'] + (['--exact'] if batch['exact'] else [])
result = subprocess.run(command, cwd=root/'v2', capture_output=True, text=True)
output = result.stdout + result.stderr
(args.evidence_dir / f'{index}-{batch["component"]}.log').write_text(output)
print(output, flush=True)
log_path = args.evidence_dir / f'{index}-{batch["component"]}.log'
returncode = execute_batch(command, root/'v2', log_path)
output = log_path.read_text(encoding='utf-8')
counts = re.findall(r'^test result: ok\. (\d+) passed; (\d+) failed; (\d+) ignored;', output, re.M)
if result.returncode or not counts or tuple(map(int, counts[-1])) != (len(batch['names']), 0, 0):
if returncode or not counts or tuple(map(int, counts[-1])) != (len(batch['names']), 0, 0):
raise ValueError('Release batch failed or nonzero/exact-count verification failed: ' + batch['selector'])
batch['passed'] = len(batch['names'])
receipt['status'] = 'passed'
Expand Down
Loading
Loading