JacobLinCool / JacobLinCool/particeps
Add ambient_light.v1 and proximity.v1
- Dominant language
- Kotlin
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
> **Scope narrowed.** The Android field-matrix and real-device evidence regime has been
> removed from this issue. What remains is the work that a build, a test, or a checked-in
> artifact can settle.
## Summary
Add separate `ambient_light.v1` and `proximity.v1` Android collector modules.
These collectors expose bounded raw sensor observations and documented hardware semantics. They must not infer room content, participant presence, attention, pocket state, or behavior.
## Requirements
### `ambient_light.v1`
- Record ambient illuminance in lux, source continuous-monotonic timestamp, and sensor accuracy.
- Define registry-declared numeric representation, valid range, unavailable/overflow behavior, source-clock basis, maximum encoded size, and event/rate bounds.
- Allow only bounded sampling and/or change-threshold controls expressed as integer physical units under #8.
- Document that sensor placement, dynamic range, calibration, screen effects, and OEM batching vary substantially.
### `proximity.v1`
- Record raw reported distance, the sensor's declared maximum range, source continuous-monotonic timestamp, and accuracy.
- Provide a deterministic near/far interpretation only when its rule and uncertainty are explicit in the schema; preserve the raw value.
- Make clear that many Android proximity sensors expose effectively binary near/far behavior and that numerical values are not comparable precision measurements across devices.
- Allow only bounded sampling and/or change-threshold controls expressed as integer physical units.
- Define missing, saturated, maximum-range, unknown-accuracy, and unusual-device behavior without substituting another sensor.
### Shared lifecycle and integration
- Keep the collectors as distinct IDs, modules, disclosures, schemas, and Parquet partitions.
- Reject enrollment when either is configured as required but the device lacks the corresponding source.
- Use shared lifecycle, event sink, clock, access, batching, backpressure, and quota contracts.
- Enforce pause/withdraw barriers and maximum encoded-event/rate bounds.
- Add Web controls, hardware capability summaries, English/Traditional Chinese disclosure, Python decoders, Parquet fixtures, and data-dictionary entries.
- Add no network, storage, logging, content capture, presence inference, or activity-inference capability.
## Acceptance criteria
- Both collectors independently round-trip valid events through encrypted storage, export/upload, Python validation, and typed Parquet.
- Required missing hardware prevents enrollment with a clear participant-facing explanation.
- Binary-only proximity devices are represented accurately and never reported as precise ranging hardware.
- Threshold and sampling controls reject negative, unbounded, over-precise, or unsupported values before signing/import.
- Duplicate/change-driven events remain within registry bounds under noisy sensor callbacks.
- Pause, resume, reboot, process recovery, sensor removal/failure, queue pressure, and quota have deterministic tests.
- No post-barrier events are appended after pause/withdraw.
- UI, logs, docs, and quality reports do not infer room content, presence, attention, or behavior.
## Documentation
Update the catalog, collector and researcher/participant guides, consent text, data dictionary, hardware-variance guidance, threat model, and analysis examples.
## Dependencies
Blocked by #10 and #11.
Contributor guide
Research direction
Start with blockers #10 and #11, then trace the shared lifecycle, event-sink, clock, access, batching, backpressure, and quota contracts. Follow both Android collectors through Web controls, disclosures, Python decoders, Parquet fixtures, and data-dictionary entries. Done means both IDs independently round-trip and all listed enrollment, bounds, lifecycle, privacy, and documentation acceptance criteria pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- android, kotlin, python
- Domain
- data, documentation, mobile, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100