Reading is an evidence-gathering process with two paths. The real app path scans media with @lss/carrier, then asks @lss/protocol to parse and verify recovered signed bytes. The deterministic test path uses @lss/reader to feed simulated CandidateFragment observations into protocol recovery without needing a camera, microphone, or MP4 file.
Real app path
@lss/web owns the interactive coordination: camera access, file import, result display, expiry checks, issuer policy, and user-facing confidence states. @lss/carrier only reports carrier evidence. @lss/protocol is the trust checkpoint for signatures and reconstructed signed envelopes.
Simulation path
@lss/reader is intentionally narrow. It is not the browser camera scanner and it is not the MP4 carrier parser. It exists so recovery behavior can be tested with deterministic candidate observations.
Confidence signals
Useful recovery facts include expected fragment count, recovered fragment count, audio candidate count, visual candidate count, checksum rejection, and whether XOR parity recovered exactly one missing data fragment. @lss/carrier adds media-facing facts such as acquisition time, candidate regions, visual observations, recovered frame count, audio confidence, and missing indexes.
Reassembly rules
The recovery layer behaves more like a packet reassembler than a scanner callback. It accepts candidate fragments in any order, groups them by fragment messageId, rejects fragments whose checksum fails, and keeps the highest-confidence candidate for each messageId, fragmentIndex, and parityIndex.
Reconstruction should expose the same kinds of facts a network stack would care about:
- how many fragments were expected,
- which indexes were observed,
- whether parity fragments were used,
- how many audio and visual candidates contributed,
- whether the final signed envelope bytes were complete enough for the caller to parse and verify.
This makes scan failures debuggable. A product can tell the difference between “no LSS fragments found”, “fragments found but too many indexes missing”, “bytes reconstructed but signature failed”, and “payload valid but expired”.
Simulated detectors
@lss/reader includes simulated detector behavior so protocol and reconstruction tests can run without a camera. @lss/carrier contains the concrete carrier scanners for browser frame pairs, imported carrier artifacts, audio samples, and Node MP4 workflows. That keeps deterministic tests and real interactive workflows separate.
Resolver handoff
The read flow should hand off reconstructed bytes, not product decisions. The caller is responsible for parsing the signed envelope, looking up the issuer public key, verifying the Ed25519 signature, checking expiry, and then passing the already-verified payload to @lss/resolver.