JacobLinCool / JacobLinCool/particeps

Add ambient_light.v1 and proximity.v1

Open
#18 0 comments 0 reactions 0 assignees View on GitHub
area: collector P2
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.