ponolock 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (173) hide show
  1. ponolock-0.3.1/.gitignore +194 -0
  2. ponolock-0.3.1/CHANGELOG.md +75 -0
  3. ponolock-0.3.1/CITATION.cff +18 -0
  4. ponolock-0.3.1/CONTRIBUTING.md +40 -0
  5. ponolock-0.3.1/LICENSE +21 -0
  6. ponolock-0.3.1/PKG-INFO +181 -0
  7. ponolock-0.3.1/README.md +104 -0
  8. ponolock-0.3.1/SECURITY.md +22 -0
  9. ponolock-0.3.1/benchmarks/scalability.py +13 -0
  10. ponolock-0.3.1/configs/benchmarks/clock_reset.json +9 -0
  11. ponolock-0.3.1/configs/benchmarks/low_resource.json +20 -0
  12. ponolock-0.3.1/configs/mmlove_vk162.json +4 -0
  13. ponolock-0.3.1/docs/README.md +13 -0
  14. ponolock-0.3.1/docs/africadrive_and_redundancy.md +101 -0
  15. ponolock-0.3.1/docs/africadrive_integration_note.md +71 -0
  16. ponolock-0.3.1/docs/africadrive_integration_prompt.md +149 -0
  17. ponolock-0.3.1/docs/api.md +118 -0
  18. ponolock-0.3.1/docs/architecture.md +40 -0
  19. ponolock-0.3.1/docs/benchmarks/2026-11-18-linux-2vcpu.json +1239 -0
  20. ponolock-0.3.1/docs/benchmarks.md +92 -0
  21. ponolock-0.3.1/docs/configuration.md +104 -0
  22. ponolock-0.3.1/docs/development/plan-0.3.md +81 -0
  23. ponolock-0.3.1/docs/embedding.md +117 -0
  24. ponolock-0.3.1/docs/gnss.md +90 -0
  25. ponolock-0.3.1/docs/hardware_validation.md +114 -0
  26. ponolock-0.3.1/docs/headless.md +69 -0
  27. ponolock-0.3.1/docs/implementation_jobs.md +22 -0
  28. ponolock-0.3.1/docs/installation.md +62 -0
  29. ponolock-0.3.1/docs/lifecycle.md +104 -0
  30. ponolock-0.3.1/docs/live_gnss_map.md +44 -0
  31. ponolock-0.3.1/docs/local_database.md +27 -0
  32. ponolock-0.3.1/docs/media_pipeline.md +77 -0
  33. ponolock-0.3.1/docs/migration.md +45 -0
  34. ponolock-0.3.1/docs/operations.md +89 -0
  35. ponolock-0.3.1/docs/operator-tools.md +92 -0
  36. ponolock-0.3.1/docs/physical_acceptance.md +99 -0
  37. ponolock-0.3.1/docs/plugin_development.md +35 -0
  38. ponolock-0.3.1/docs/quickstart.md +64 -0
  39. ponolock-0.3.1/docs/release.md +67 -0
  40. ponolock-0.3.1/docs/session_format.md +126 -0
  41. ponolock-0.3.1/docs/studio_api.md +29 -0
  42. ponolock-0.3.1/docs/synchronization.md +48 -0
  43. ponolock-0.3.1/docs/timestamps.md +78 -0
  44. ponolock-0.3.1/docs/troubleshooting.md +58 -0
  45. ponolock-0.3.1/docs/verification.md +57 -0
  46. ponolock-0.3.1/examples/camera_only.py +7 -0
  47. ponolock-0.3.1/examples/consumer_app/README.md +16 -0
  48. ponolock-0.3.1/examples/consumer_app/pyproject.toml +16 -0
  49. ponolock-0.3.1/examples/consumer_app/src/trip_logger/__init__.py +1 -0
  50. ponolock-0.3.1/examples/consumer_app/src/trip_logger/app.py +92 -0
  51. ponolock-0.3.1/examples/custom_algorithm.py +17 -0
  52. ponolock-0.3.1/examples/gps_only.py +7 -0
  53. ponolock-0.3.1/examples/mmlove_vk162.py +19 -0
  54. ponolock-0.3.1/examples/multi_camera_multi_gnss.py +10 -0
  55. ponolock-0.3.1/examples/offline_alignment.py +10 -0
  56. ponolock-0.3.1/examples/simulated_recording.py +11 -0
  57. ponolock-0.3.1/pyproject.toml +106 -0
  58. ponolock-0.3.1/research/charter.md +46 -0
  59. ponolock-0.3.1/research/experiment_protocol.md +30 -0
  60. ponolock-0.3.1/research/methodology.md +36 -0
  61. ponolock-0.3.1/research/paper_outline.md +29 -0
  62. ponolock-0.3.1/research/questions.md +36 -0
  63. ponolock-0.3.1/src/ponolock/__init__.py +93 -0
  64. ponolock-0.3.1/src/ponolock/_version.py +3 -0
  65. ponolock-0.3.1/src/ponolock/api/__init__.py +1 -0
  66. ponolock-0.3.1/src/ponolock/api/app.py +427 -0
  67. ponolock-0.3.1/src/ponolock/api/launch.py +78 -0
  68. ponolock-0.3.1/src/ponolock/api/media.py +206 -0
  69. ponolock-0.3.1/src/ponolock/api/research.py +184 -0
  70. ponolock-0.3.1/src/ponolock/api/runtime.py +89 -0
  71. ponolock-0.3.1/src/ponolock/auth/__init__.py +3 -0
  72. ponolock-0.3.1/src/ponolock/auth/accounts.py +177 -0
  73. ponolock-0.3.1/src/ponolock/benchmarks/__init__.py +3 -0
  74. ponolock-0.3.1/src/ponolock/benchmarks/recording.py +318 -0
  75. ponolock-0.3.1/src/ponolock/benchmarks/synthetic.py +399 -0
  76. ponolock-0.3.1/src/ponolock/cli.py +518 -0
  77. ponolock-0.3.1/src/ponolock/clock/__init__.py +5 -0
  78. ponolock-0.3.1/src/ponolock/clock/models.py +185 -0
  79. ponolock-0.3.1/src/ponolock/config.py +26 -0
  80. ponolock-0.3.1/src/ponolock/documentation.py +47 -0
  81. ponolock-0.3.1/src/ponolock/errors.py +66 -0
  82. ponolock-0.3.1/src/ponolock/metrics/__init__.py +29 -0
  83. ponolock-0.3.1/src/ponolock/metrics/quality.py +35 -0
  84. ponolock-0.3.1/src/ponolock/metrics/resources.py +40 -0
  85. ponolock-0.3.1/src/ponolock/models.py +90 -0
  86. ponolock-0.3.1/src/ponolock/plugins/__init__.py +36 -0
  87. ponolock-0.3.1/src/ponolock/preflight.py +256 -0
  88. ponolock-0.3.1/src/ponolock/profiles.py +110 -0
  89. ponolock-0.3.1/src/ponolock/progress.py +120 -0
  90. ponolock-0.3.1/src/ponolock/py.typed +0 -0
  91. ponolock-0.3.1/src/ponolock/recording/__init__.py +3 -0
  92. ponolock-0.3.1/src/ponolock/recording/inspection.py +312 -0
  93. ponolock-0.3.1/src/ponolock/recording/lifecycle.py +174 -0
  94. ponolock-0.3.1/src/ponolock/recording/mkv.py +118 -0
  95. ponolock-0.3.1/src/ponolock/recording/playback.py +175 -0
  96. ponolock-0.3.1/src/ponolock/recording/preview.py +196 -0
  97. ponolock-0.3.1/src/ponolock/recording/recorder.py +1083 -0
  98. ponolock-0.3.1/src/ponolock/recording/verification.py +342 -0
  99. ponolock-0.3.1/src/ponolock/recording/writer.py +367 -0
  100. ponolock-0.3.1/src/ponolock/reporting.py +82 -0
  101. ponolock-0.3.1/src/ponolock/sources/__init__.py +6 -0
  102. ponolock-0.3.1/src/ponolock/sources/base.py +22 -0
  103. ponolock-0.3.1/src/ponolock/sources/camera.py +224 -0
  104. ponolock-0.3.1/src/ponolock/sources/discovery.py +301 -0
  105. ponolock-0.3.1/src/ponolock/sources/ffmpeg_probe.py +161 -0
  106. ponolock-0.3.1/src/ponolock/sources/gnss.py +405 -0
  107. ponolock-0.3.1/src/ponolock/sources/identity.py +79 -0
  108. ponolock-0.3.1/src/ponolock/sources/simulated.py +108 -0
  109. ponolock-0.3.1/src/ponolock/status.py +99 -0
  110. ponolock-0.3.1/src/ponolock/storage/__init__.py +3 -0
  111. ponolock-0.3.1/src/ponolock/storage/database.py +132 -0
  112. ponolock-0.3.1/src/ponolock/storage/importer.py +124 -0
  113. ponolock-0.3.1/src/ponolock/storage/session.py +215 -0
  114. ponolock-0.3.1/src/ponolock/studio/static/assets/mark.svg +1 -0
  115. ponolock-0.3.1/src/ponolock/studio/static/css/studio.css +31 -0
  116. ponolock-0.3.1/src/ponolock/studio/static/js/api.js +16 -0
  117. ponolock-0.3.1/src/ponolock/studio/static/js/app.js +142 -0
  118. ponolock-0.3.1/src/ponolock/studio/static/js/gnss-map-core.js +45 -0
  119. ponolock-0.3.1/src/ponolock/studio/static/js/gnss-map.js +78 -0
  120. ponolock-0.3.1/src/ponolock/studio/static/js/media.js +288 -0
  121. ponolock-0.3.1/src/ponolock/studio/static/js/research.js +79 -0
  122. ponolock-0.3.1/src/ponolock/studio/static/js/ui.js +72 -0
  123. ponolock-0.3.1/src/ponolock/studio/static/js/views.js +157 -0
  124. ponolock-0.3.1/src/ponolock/studio/static/vendor/leaflet/LICENSE +26 -0
  125. ponolock-0.3.1/src/ponolock/studio/static/vendor/leaflet/images/layers-2x.png +0 -0
  126. ponolock-0.3.1/src/ponolock/studio/static/vendor/leaflet/images/layers.png +0 -0
  127. ponolock-0.3.1/src/ponolock/studio/static/vendor/leaflet/leaflet.css +661 -0
  128. ponolock-0.3.1/src/ponolock/studio/static/vendor/leaflet/leaflet.js +6 -0
  129. ponolock-0.3.1/src/ponolock/studio/templates/index.html +33 -0
  130. ponolock-0.3.1/src/ponolock/sync/__init__.py +20 -0
  131. ponolock-0.3.1/src/ponolock/sync/association.py +212 -0
  132. ponolock-0.3.1/src/ponolock/sync/diagnostics.py +185 -0
  133. ponolock-0.3.1/src/ponolock/sync/interpolation.py +64 -0
  134. ponolock-0.3.1/src/ponolock/sync/registry.py +44 -0
  135. ponolock-0.3.1/src/ponolock/timing.py +160 -0
  136. ponolock-0.3.1/tests/browser_check.py +168 -0
  137. ponolock-0.3.1/tests/compat/test_africadrive_contract.py +176 -0
  138. ponolock-0.3.1/tests/compat/test_legacy_sessions.py +57 -0
  139. ponolock-0.3.1/tests/conftest.py +5 -0
  140. ponolock-0.3.1/tests/docs/test_doc_examples.py +41 -0
  141. ponolock-0.3.1/tests/faults.py +113 -0
  142. ponolock-0.3.1/tests/fixtures/legacy_0_2_3/cameras/front.avi +0 -0
  143. ponolock-0.3.1/tests/fixtures/legacy_0_2_3/cameras/front_frames.csv +16 -0
  144. ponolock-0.3.1/tests/fixtures/legacy_0_2_3/configuration.json +54 -0
  145. ponolock-0.3.1/tests/fixtures/legacy_0_2_3/events/system_events.jsonl +2 -0
  146. ponolock-0.3.1/tests/fixtures/legacy_0_2_3/gnss/gnss_fixes.csv +9 -0
  147. ponolock-0.3.1/tests/fixtures/legacy_0_2_3/gnss/gnss_raw.nmea +8 -0
  148. ponolock-0.3.1/tests/fixtures/legacy_0_2_3/manifest.json +97 -0
  149. ponolock-0.3.1/tests/fixtures/legacy_0_2_3/quality/recording_quality.json +20 -0
  150. ponolock-0.3.1/tests/fixtures/legacy_0_2_3/timing/clock_domains.json +18 -0
  151. ponolock-0.3.1/tests/fixtures/legacy_0_2_3/timing/clock_mappings.json +4 -0
  152. ponolock-0.3.1/tests/gnss-map.test.cjs +66 -0
  153. ponolock-0.3.1/tests/integration/__init__.py +0 -0
  154. ponolock-0.3.1/tests/integration/conftest.py +20 -0
  155. ponolock-0.3.1/tests/integration/helpers.py +14 -0
  156. ponolock-0.3.1/tests/integration/test_api.py +133 -0
  157. ponolock-0.3.1/tests/integration/test_device_identity.py +27 -0
  158. ponolock-0.3.1/tests/integration/test_headless.py +195 -0
  159. ponolock-0.3.1/tests/integration/test_interrupted_recovery.py +86 -0
  160. ponolock-0.3.1/tests/integration/test_lifecycle_integrity.py +368 -0
  161. ponolock-0.3.1/tests/integration/test_media.py +240 -0
  162. ponolock-0.3.1/tests/integration/test_release_regressions.py +71 -0
  163. ponolock-0.3.1/tests/integration/test_reliability.py +197 -0
  164. ponolock-0.3.1/tests/integration/test_stream_mkv.py +173 -0
  165. ponolock-0.3.1/tests/release/inspect_artifacts.py +91 -0
  166. ponolock-0.3.1/tests/release/smoke.py +185 -0
  167. ponolock-0.3.1/tests/synthetic/test_benchmarks.py +44 -0
  168. ponolock-0.3.1/tests/unit/test_core.py +105 -0
  169. ponolock-0.3.1/tests/unit/test_discovery_identity.py +174 -0
  170. ponolock-0.3.1/tests/unit/test_gnss.py +244 -0
  171. ponolock-0.3.1/tests/unit/test_operator_tools.py +102 -0
  172. ponolock-0.3.1/tests/unit/test_sync_diagnostics.py +56 -0
  173. ponolock-0.3.1/tests/unit/test_synchronization.py +84 -0
@@ -0,0 +1,194 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py,cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+
74
+ # PyBuilder
75
+ .pybuilder/
76
+ target/
77
+
78
+ # Jupyter Notebook
79
+ .ipynb_checkpoints
80
+
81
+ # IPython
82
+ profile_default/
83
+ ipython_config.py
84
+
85
+ # pyenv
86
+ # For a library or package, you might want to ignore these files since the code is
87
+ # intended to run in multiple environments; otherwise, check them in:
88
+ # .python-version
89
+
90
+ # pipenv
91
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
93
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
94
+ # install all needed dependencies.
95
+ #Pipfile.lock
96
+
97
+ # UV
98
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
100
+ # commonly ignored for libraries.
101
+ #uv.lock
102
+
103
+ # poetry
104
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
106
+ # commonly ignored for libraries.
107
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108
+ #poetry.lock
109
+
110
+ # pdm
111
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
112
+ #pdm.lock
113
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
114
+ # in version control.
115
+ # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
116
+ .pdm.toml
117
+ .pdm-python
118
+ .pdm-build/
119
+
120
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
121
+ __pypackages__/
122
+
123
+ # Celery stuff
124
+ celerybeat-schedule
125
+ celerybeat.pid
126
+
127
+ # SageMath parsed files
128
+ *.sage.py
129
+
130
+ # Environments
131
+ .env
132
+ .venv
133
+ env/
134
+ venv/
135
+ ENV/
136
+ env.bak/
137
+ venv.bak/
138
+
139
+ # Spyder project settings
140
+ .spyderproject
141
+ .spyproject
142
+
143
+ # Rope project settings
144
+ .ropeproject
145
+
146
+ # mkdocs documentation
147
+ /site
148
+
149
+ # mypy
150
+ .mypy_cache/
151
+ .dmypy.json
152
+ dmypy.json
153
+
154
+ # Pyre type checker
155
+ .pyre/
156
+
157
+ # pytype static type analyzer
158
+ .pytype/
159
+
160
+ # Cython debug symbols
161
+ cython_debug/
162
+
163
+ # PyCharm
164
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
165
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
166
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
167
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
168
+ #.idea/
169
+
170
+ # Ruff stuff:
171
+ .ruff_cache/
172
+
173
+ # PyPI configuration file
174
+ .pypirc
175
+
176
+ # Cursor
177
+ # Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to
178
+ # exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
179
+ # refer to https://docs.cursor.com/context/ignore-files
180
+ .cursorignore
181
+ .cursorindexingignore
182
+
183
+ # Local research data and credentials (never commit locations or sessions)
184
+ recordings/
185
+ .ponolock/
186
+ artifacts/
187
+ *.sqlite3
188
+ *.sqlite3-*
189
+ *.db
190
+ *.db-*
191
+ playwright-report/
192
+ test-results/
193
+ .venv311/
194
+ *.local.json
@@ -0,0 +1,75 @@
1
+ # Changelog
2
+
3
+ All notable changes are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
5
+ [Semantic Versioning](https://semver.org/) as described in `docs/release.md`.
6
+
7
+ ## [0.3.1] - 2026-11-18
8
+
9
+ - Recover per media file/index; preserve gaps when segments are missing. Withhold
10
+ ambiguous mappings instead of assigning the wrong timestamps to surviving frames.
11
+ - Fsync each rollover segment before publishing it closed; propagate flush failures.
12
+ - Preserve already-received GNSS shutdown tails and their actual receipt times.
13
+ - Add strict versioned profiles, guided read-only setup, migration and schema commands.
14
+ - Add consumer-owned progress events and CLI bars/JSON progress for recording,
15
+ verification, hashing, inspection, recovery, reporting and benchmarks.
16
+ - Add redacted JSON/HTML/ZIP diagnostic reports and bundled offline documentation.
17
+ - Gate publication on the full Linux/Windows checks; isolate TestPyPI project downloads.
18
+ - Fix a Studio map renderer teardown race detected by the real-browser workflow.
19
+ - AfricaDrive must allow tied GNSS receipts from serial batches; do not synthesize times.
20
+ Hardware timing/accuracy/endurance acceptance remains separate and unrun.
21
+
22
+ ## [0.3.0] - 2026-11-18
23
+
24
+ Unpublished release candidate. Session format 1.1 (additive over 1.0).
25
+ See `docs/migration.md` for behaviour changes.
26
+
27
+ ### Added
28
+ - Read-only discovery (`list_cameras`, `list_serial_ports`, `list_devices`, `DeviceInfo`)
29
+ with identity basis, stability and limitations; explicit `probe_camera`.
30
+ - Identity resolution on every open/reconnect with no fallback (`DeviceIdentityError`).
31
+ - Typed exception hierarchy subclassing the builtin types raised by 0.2.
32
+ - Explicit lifecycle state machine (`RecorderState`), `abort()`, `close()`, `status()`
33
+ (`RecorderStatus`/`SourceStatus`), bounded `subscribe()` event queues, `preflight()`.
34
+ - `RecordingOptions`: disk reserve with live monitor, opt-in rollover, flush/fsync
35
+ policy, drain/join/stall timeouts.
36
+ - Session states `partial`, `aborted`, `failed` and derived `interrupted` (recording lock).
37
+ - Per-source accounting (`acquired = written + queue_dropped + writer_dropped`).
38
+ - `muxer="stream_mkv"`: crash-tolerant streaming Matroska for MJPEG packets, byte-exact.
39
+ - `inspect_session` / `recover_session` (non-destructive, hash-proven) and CLI
40
+ `verify`, `inspect`, `recover`, `diagnose`, `preflight`, `benchmark-recording`.
41
+ - Byte-exact NMEA framing, solution-epoch grouping, GNSS time segments, course over
42
+ ground, passive receiver adapter interface.
43
+ - Timestamp provenance (`timing/timestamp_semantics.json`), capability-gated Linux V4L2
44
+ driver timestamps, read-start times, serial first/last-byte receipt times.
45
+ - Synchronization diagnostics and held-out clock-mapping evaluation.
46
+ - Preview decoding of undecoded MJPEG packets on the preview thread at reduced scale.
47
+ - `camera-headless` extra; OpenCV 5 support (tested in CI).
48
+ - Recording-pipeline benchmark harness and published measurements.
49
+ - Documentation set (installation, quickstarts, embedding, API, configuration, lifecycle,
50
+ timing, GNSS, session format, operations, benchmarks, physical acceptance, migration,
51
+ release) with executed examples; example consumer application.
52
+ - AfricaDrive contract tests and a 0.2.3 legacy-session fixture.
53
+ - Trusted-publishing release workflow with TestPyPI stage and artifact inspection.
54
+
55
+ ### Changed
56
+ - `discover_cameras()` no longer opens camera streams by default.
57
+ - `complete_with_errors` is now written as `partial` (old value still read).
58
+ - Timing rows are handed to the OS every row (was every 20 rows).
59
+ - CLI `record` disables unused previews and exits 3 unless the session is `complete`.
60
+ - Simulated GNSS emits RMC+GGA epochs at a synthetic open-ocean location.
61
+ - Single-sourced version; fixed stale versions in CLI, manifests and Studio.
62
+
63
+ ### Fixed
64
+ - Partial serial reads split one NMEA sentence into two malformed records.
65
+ - GNSS time-of-day parsing ignored values with a UTC offset suffix.
66
+ - CI formatting/mypy failures on Linux.
67
+
68
+ ## [0.2.3] - 2026-11-12
69
+ Downstream physical-test corrections (see `docs/headless.md`). Not published to PyPI.
70
+
71
+ ## [0.2.0] – [0.2.2]
72
+ Headless taps, offline reconciliation, raw serial bytes, NMEA validation. Not published.
73
+
74
+ ## [0.1.0] - 2026-11-07
75
+ Initial research release (Core, Studio, Research). Not published to PyPI.
@@ -0,0 +1,18 @@
1
+ cff-version: 1.2.0
2
+ message: Please cite the software version and commit used in your experiments.
3
+ title: 'PonoLock: Uncertainty-Aware Temporal Alignment of Low-Cost Camera and GNSS Networks'
4
+ type: software
5
+ authors:
6
+ - family-names: Motsoehli
7
+ given-names: Moseli
8
+ - name: PonoLock contributors
9
+ version: 0.1.0
10
+ date-released: '2026-11-07'
11
+ repository-code: 'https://github.com/Mind-Forge-AI/PonoLock'
12
+ license: MIT
13
+ keywords:
14
+ - synchronization
15
+ - GNSS
16
+ - uncertainty
17
+ - sensor networks
18
+ - African research
@@ -0,0 +1,40 @@
1
+ # Contributing
2
+
3
+ PonoLock welcomes research, engineering, documentation and hardware-validation
4
+ contributions. Begin with a reproducible problem or a falsifiable experimental question.
5
+ Follow the [research charter](research/charter.md) and preserve application independence.
6
+
7
+ ```powershell
8
+ py -3.11 -m venv .venv
9
+ .venv\Scripts\python -m pip install -e ".[all,dev]"
10
+ .venv\Scripts\python -m pytest -q
11
+ .venv\Scripts\python -m ruff check src tests examples benchmarks
12
+ .venv\Scripts\python -m ruff format --check src tests examples benchmarks
13
+ .venv\Scripts\python -m mypy src/ponolock
14
+ .venv\Scripts\python -m build
15
+ .venv\Scripts\python tests\release\inspect_artifacts.py dist
16
+ .venv\Scripts\python tests\release\smoke.py (Get-Item dist\*.whl)
17
+ ```
18
+
19
+ Tests are organised as `tests/unit` (pure logic), `tests/integration` (real recorder
20
+ threads, files and decoding with simulated or fault-injecting sources from
21
+ `tests/faults.py`), `tests/compat` (0.2.3 sessions and the AfricaDrive contract),
22
+ `tests/docs` (executes documentation examples marked `<!-- doctest -->`), `tests/synthetic`
23
+ (research benchmarks) and `tests/release` (artifact inspection and clean-environment
24
+ smoke tests). Assertions must check saved content (decoded pixels, raw bytes, rows), not
25
+ only the recorder's own counters. Simulations are never presented as hardware evidence.
26
+
27
+ Real-browser verification: `python -m playwright install chromium`, then
28
+ `python tests/browser_check.py`. It uses temporary accounts and simulated devices.
29
+ `--executable PATH` can use an existing Chromium installation.
30
+
31
+ Keep optional dependencies lazy, respect public interfaces, validate configuration, and
32
+ test meaningful lifecycle/failure cases. New drivers and algorithms must state their
33
+ timing evidence, unknowns, boundedness and failure behavior. Do not replace missing
34
+ historical observations with current timestamps. Review UI keyboard access and test
35
+ backend authorization independently of navigation visibility.
36
+
37
+ Pull requests should explain the concrete problem and resulting behavior, validation,
38
+ scientific limits and any hardware-specific assumptions. Do not commit recordings,
39
+ credentials, raw positions, private images, personal databases or machine-specific device
40
+ identifiers. Release process and versioning: see `docs/release.md`. Existing MIT licensing applies to contributions unless separately agreed.
ponolock-0.3.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Moseli Motsoehli
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,181 @@
1
+ Metadata-Version: 2.4
2
+ Name: ponolock
3
+ Version: 0.3.1
4
+ Summary: Dependable multicamera and GNSS recording with explicit timestamp provenance, loss accounting and offline verification
5
+ Project-URL: Homepage, https://github.com/Mind-Forge-AI/PonoLock
6
+ Project-URL: Documentation, https://pypi.org/project/ponolock/#description
7
+ Project-URL: Repository, https://github.com/Mind-Forge-AI/PonoLock
8
+ Project-URL: Changelog, https://github.com/Mind-Forge-AI/PonoLock/blob/main/CHANGELOG.md
9
+ Project-URL: Issues, https://github.com/Mind-Forge-AI/PonoLock/issues
10
+ Author: Moseli Motsoehli, PonoLock contributors
11
+ Maintainer: Mindforge AI
12
+ License-Expression: MIT
13
+ License-File: LICENSE
14
+ Keywords: camera,data-acquisition,gnss,gps,nmea,recording,stereo,synchronization,timestamps
15
+ Classifier: Development Status :: 3 - Alpha
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: Science/Research
18
+ Classifier: Operating System :: Microsoft :: Windows
19
+ Classifier: Operating System :: POSIX :: Linux
20
+ Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3 :: Only
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Classifier: Programming Language :: Python :: 3.13
25
+ Classifier: Topic :: Multimedia :: Video :: Capture
26
+ Classifier: Topic :: Scientific/Engineering
27
+ Classifier: Topic :: Scientific/Engineering :: GIS
28
+ Classifier: Typing :: Typed
29
+ Requires-Python: >=3.11
30
+ Requires-Dist: pydantic<3,>=2.10
31
+ Provides-Extra: all
32
+ Requires-Dist: argon2-cffi<26,>=23.1; extra == 'all'
33
+ Requires-Dist: cv2-enumerate-cameras<2,>=1.1; extra == 'all'
34
+ Requires-Dist: fastapi<1,>=0.115; extra == 'all'
35
+ Requires-Dist: markdown<4,>=3.7; extra == 'all'
36
+ Requires-Dist: matplotlib<4,>=3.9; extra == 'all'
37
+ Requires-Dist: numpy<3,>=1.26; extra == 'all'
38
+ Requires-Dist: opencv-python<6,>=4.10; extra == 'all'
39
+ Requires-Dist: pynmea2<2,>=1.19; extra == 'all'
40
+ Requires-Dist: pyserial<4,>=3.5; extra == 'all'
41
+ Requires-Dist: uvicorn<1,>=0.32; extra == 'all'
42
+ Requires-Dist: websockets<17,>=14; extra == 'all'
43
+ Provides-Extra: camera
44
+ Requires-Dist: cv2-enumerate-cameras<2,>=1.1; extra == 'camera'
45
+ Requires-Dist: numpy<3,>=1.26; extra == 'camera'
46
+ Requires-Dist: opencv-python<6,>=4.10; extra == 'camera'
47
+ Provides-Extra: camera-headless
48
+ Requires-Dist: cv2-enumerate-cameras<2,>=1.1; extra == 'camera-headless'
49
+ Requires-Dist: numpy<3,>=1.26; extra == 'camera-headless'
50
+ Requires-Dist: opencv-python-headless<6,>=4.10; extra == 'camera-headless'
51
+ Provides-Extra: dev
52
+ Requires-Dist: build<2,>=1.2; extra == 'dev'
53
+ Requires-Dist: httpx<1,>=0.28; extra == 'dev'
54
+ Requires-Dist: mypy<2,>=1.14; extra == 'dev'
55
+ Requires-Dist: pip-audit<3,>=2.7; extra == 'dev'
56
+ Requires-Dist: playwright<2,>=1.50; extra == 'dev'
57
+ Requires-Dist: pytest<10,>=8.3; extra == 'dev'
58
+ Requires-Dist: ruff<1,>=0.11; extra == 'dev'
59
+ Requires-Dist: twine<8,>=6.1; extra == 'dev'
60
+ Requires-Dist: types-markdown<4,>=3.7; extra == 'dev'
61
+ Provides-Extra: docs
62
+ Requires-Dist: markdown<4,>=3.7; extra == 'docs'
63
+ Provides-Extra: gnss
64
+ Requires-Dist: pynmea2<2,>=1.19; extra == 'gnss'
65
+ Requires-Dist: pyserial<4,>=3.5; extra == 'gnss'
66
+ Provides-Extra: parquet
67
+ Requires-Dist: pyarrow<24,>=18; extra == 'parquet'
68
+ Provides-Extra: research
69
+ Requires-Dist: matplotlib<4,>=3.9; extra == 'research'
70
+ Requires-Dist: numpy<3,>=1.26; extra == 'research'
71
+ Provides-Extra: studio
72
+ Requires-Dist: argon2-cffi<26,>=23.1; extra == 'studio'
73
+ Requires-Dist: fastapi<1,>=0.115; extra == 'studio'
74
+ Requires-Dist: uvicorn<1,>=0.32; extra == 'studio'
75
+ Requires-Dist: websockets<17,>=14; extra == 'studio'
76
+ Description-Content-Type: text/markdown
77
+
78
+ # PonoLock
79
+
80
+ **Dependable multicamera and GNSS recording that tells you exactly what its timestamps
81
+ mean, what it lost, and what it cannot know.**
82
+
83
+ PonoLock records any number of USB cameras (including side-by-side stereo) and serial
84
+ NMEA GNSS receivers concurrently, from one Python library. It preserves original camera
85
+ MJPEG packets and every received GNSS byte, keeps each kind of timestamp separate with
86
+ its provenance, accounts for every observation it acquired, and verifies sessions
87
+ offline. The same engine powers the command line, an optional local Studio and your own
88
+ applications.
89
+
90
+ [![PyPI](https://img.shields.io/pypi/v/ponolock)](https://pypi.org/project/ponolock/)
91
+ [![Python](https://img.shields.io/pypi/pyversions/ponolock)](https://pypi.org/project/ponolock/)
92
+ [![Checks](https://github.com/Mind-Forge-AI/PonoLock/actions/workflows/ci.yml/badge.svg)](https://github.com/Mind-Forge-AI/PonoLock/actions/workflows/ci.yml)
93
+
94
+ ```console
95
+ pip install "ponolock[camera,gnss]"
96
+ ponolock record --simulate --duration 5 --muxer stream_mkv
97
+ ponolock verify recordings/session_*
98
+ ```
99
+
100
+ ## Embed it
101
+
102
+ <!-- doctest -->
103
+ ```python
104
+ import tempfile, time
105
+ from ponolock import Recorder, RecordingOptions, SensorConfig, verify_session
106
+
107
+ recorder = Recorder(tempfile.mkdtemp(), preview_enabled=False,
108
+ options=RecordingOptions(disk_reserve_bytes=0))
109
+ recorder.add_source(SensorConfig(name="front", kind="camera", simulated=True,
110
+ width=320, height=240, fps=15, muxer="stream_mkv"))
111
+ recorder.add_source(SensorConfig(name="gnss", kind="gnss", simulated=True))
112
+ with recorder:
113
+ session = recorder.start()
114
+ time.sleep(1)
115
+ print(verify_session(session)["software_reconciliation_passed"]) # True
116
+ ```
117
+
118
+ For real devices, bind identities from `ponolock devices` (which opens nothing) with
119
+ `SensorConfig(persistent_id=...)`. PonoLock never silently switches to another camera or
120
+ receiver when indexes or COM numbers change.
121
+
122
+ ## What is supported
123
+
124
+ | Capability | Status |
125
+ |---|---|
126
+ | N cameras + M GNSS receivers, one acquisition owner per device | Implemented |
127
+ | UVC cameras via OpenCV (DirectShow/MSMF on Windows, V4L2 on Linux); side-by-side stereo | Implemented |
128
+ | MJPEG packet passthrough; JPEG re-encode; lossless FFV1 | Implemented (FFV1 is CPU-bound, see benchmarks) |
129
+ | Crash-tolerant streaming MKV, rollover, disk reserve, recovery of interrupted sessions | Implemented |
130
+ | Serial NMEA with byte-exact raw logs, epoch grouping, validity/staleness | Implemented |
131
+ | Host receipt timestamps (all sources); Linux V4L2 driver timestamps | Implemented; V4L2 hardware-unvalidated |
132
+ | Exposure timestamps, hardware triggering, PPS capture | **Not implemented** |
133
+ | Exposure synchronization, positioning accuracy, sensor fusion | **Not claimed** |
134
+ | Python 3.11–3.13 on Windows and Linux | Tested in CI (software only) |
135
+
136
+ Physical validation status and procedures: [physical acceptance](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/physical_acceptance.md).
137
+ Measured software throughput: [benchmarks](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/benchmarks.md).
138
+
139
+ ## Documentation
140
+
141
+ Full documentation ships in the package, including when the source repository is private:
142
+
143
+ ```console
144
+ pip install "ponolock[docs]"
145
+ ponolock docs --output ponolock-manual
146
+ ```
147
+
148
+ Open `ponolock-manual/index.html`. Guided configuration: `ponolock setup`.
149
+ Progress bars are enabled by default; `--progress-json` supports integrations.
150
+ `ponolock report SESSION --output REPORT_DIR` writes redacted JSON, HTML and ZIP.
151
+
152
+
153
+ * [Installation and extras](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/installation.md) ·
154
+ [Quickstart (simulation and real devices)](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/quickstart.md)
155
+ * [Embedding in Python](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/embedding.md) ·
156
+ [API reference](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/api.md) ·
157
+ [Configuration and device identity](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/configuration.md)
158
+ * [Lifecycle, ownership and concurrency](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/lifecycle.md) ·
159
+ [Timestamps and synchronization evidence](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/timestamps.md) ·
160
+ [GNSS semantics](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/gnss.md)
161
+ * [Session format](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/session_format.md) ·
162
+ [Long sessions, durability, recovery, troubleshooting](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/operations.md)
163
+ * [Migration from 0.2](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/migration.md) ·
164
+ [Release and versioning policy](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/release.md) ·
165
+ [Changelog](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/CHANGELOG.md) ·
166
+ [Contributing](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/CONTRIBUTING.md)
167
+ * Studio and research: [Studio](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/studio_api.md),
168
+ [synchronization research methods](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/synchronization.md),
169
+ [research charter](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/research/charter.md)
170
+
171
+ ## Honest limits
172
+
173
+ A common host clock, configured FPS, nearest-neighbour matching or visually aligned
174
+ previews do not prove exposure synchronization. Host receipt time follows exposure by an
175
+ unknown delay. HDOP and satellite count are not accuracy. Zero queue drops is not zero
176
+ device-side loss. Unknown uncertainty is recorded as unknown, never zero, and gaps are
177
+ never filled by interpolation.
178
+
179
+ PonoLock was motivated by data-integrity needs in the AfricaDrive dataset project and is
180
+ developed independently of it. Images, positions and credentials stay local; PonoLock has
181
+ no telemetry. MIT licensed.
@@ -0,0 +1,104 @@
1
+ # PonoLock
2
+
3
+ **Dependable multicamera and GNSS recording that tells you exactly what its timestamps
4
+ mean, what it lost, and what it cannot know.**
5
+
6
+ PonoLock records any number of USB cameras (including side-by-side stereo) and serial
7
+ NMEA GNSS receivers concurrently, from one Python library. It preserves original camera
8
+ MJPEG packets and every received GNSS byte, keeps each kind of timestamp separate with
9
+ its provenance, accounts for every observation it acquired, and verifies sessions
10
+ offline. The same engine powers the command line, an optional local Studio and your own
11
+ applications.
12
+
13
+ [![PyPI](https://img.shields.io/pypi/v/ponolock)](https://pypi.org/project/ponolock/)
14
+ [![Python](https://img.shields.io/pypi/pyversions/ponolock)](https://pypi.org/project/ponolock/)
15
+ [![Checks](https://github.com/Mind-Forge-AI/PonoLock/actions/workflows/ci.yml/badge.svg)](https://github.com/Mind-Forge-AI/PonoLock/actions/workflows/ci.yml)
16
+
17
+ ```console
18
+ pip install "ponolock[camera,gnss]"
19
+ ponolock record --simulate --duration 5 --muxer stream_mkv
20
+ ponolock verify recordings/session_*
21
+ ```
22
+
23
+ ## Embed it
24
+
25
+ <!-- doctest -->
26
+ ```python
27
+ import tempfile, time
28
+ from ponolock import Recorder, RecordingOptions, SensorConfig, verify_session
29
+
30
+ recorder = Recorder(tempfile.mkdtemp(), preview_enabled=False,
31
+ options=RecordingOptions(disk_reserve_bytes=0))
32
+ recorder.add_source(SensorConfig(name="front", kind="camera", simulated=True,
33
+ width=320, height=240, fps=15, muxer="stream_mkv"))
34
+ recorder.add_source(SensorConfig(name="gnss", kind="gnss", simulated=True))
35
+ with recorder:
36
+ session = recorder.start()
37
+ time.sleep(1)
38
+ print(verify_session(session)["software_reconciliation_passed"]) # True
39
+ ```
40
+
41
+ For real devices, bind identities from `ponolock devices` (which opens nothing) with
42
+ `SensorConfig(persistent_id=...)`. PonoLock never silently switches to another camera or
43
+ receiver when indexes or COM numbers change.
44
+
45
+ ## What is supported
46
+
47
+ | Capability | Status |
48
+ |---|---|
49
+ | N cameras + M GNSS receivers, one acquisition owner per device | Implemented |
50
+ | UVC cameras via OpenCV (DirectShow/MSMF on Windows, V4L2 on Linux); side-by-side stereo | Implemented |
51
+ | MJPEG packet passthrough; JPEG re-encode; lossless FFV1 | Implemented (FFV1 is CPU-bound, see benchmarks) |
52
+ | Crash-tolerant streaming MKV, rollover, disk reserve, recovery of interrupted sessions | Implemented |
53
+ | Serial NMEA with byte-exact raw logs, epoch grouping, validity/staleness | Implemented |
54
+ | Host receipt timestamps (all sources); Linux V4L2 driver timestamps | Implemented; V4L2 hardware-unvalidated |
55
+ | Exposure timestamps, hardware triggering, PPS capture | **Not implemented** |
56
+ | Exposure synchronization, positioning accuracy, sensor fusion | **Not claimed** |
57
+ | Python 3.11–3.13 on Windows and Linux | Tested in CI (software only) |
58
+
59
+ Physical validation status and procedures: [physical acceptance](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/physical_acceptance.md).
60
+ Measured software throughput: [benchmarks](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/benchmarks.md).
61
+
62
+ ## Documentation
63
+
64
+ Full documentation ships in the package, including when the source repository is private:
65
+
66
+ ```console
67
+ pip install "ponolock[docs]"
68
+ ponolock docs --output ponolock-manual
69
+ ```
70
+
71
+ Open `ponolock-manual/index.html`. Guided configuration: `ponolock setup`.
72
+ Progress bars are enabled by default; `--progress-json` supports integrations.
73
+ `ponolock report SESSION --output REPORT_DIR` writes redacted JSON, HTML and ZIP.
74
+
75
+
76
+ * [Installation and extras](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/installation.md) ·
77
+ [Quickstart (simulation and real devices)](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/quickstart.md)
78
+ * [Embedding in Python](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/embedding.md) ·
79
+ [API reference](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/api.md) ·
80
+ [Configuration and device identity](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/configuration.md)
81
+ * [Lifecycle, ownership and concurrency](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/lifecycle.md) ·
82
+ [Timestamps and synchronization evidence](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/timestamps.md) ·
83
+ [GNSS semantics](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/gnss.md)
84
+ * [Session format](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/session_format.md) ·
85
+ [Long sessions, durability, recovery, troubleshooting](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/operations.md)
86
+ * [Migration from 0.2](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/migration.md) ·
87
+ [Release and versioning policy](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/release.md) ·
88
+ [Changelog](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/CHANGELOG.md) ·
89
+ [Contributing](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/CONTRIBUTING.md)
90
+ * Studio and research: [Studio](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/studio_api.md),
91
+ [synchronization research methods](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/docs/synchronization.md),
92
+ [research charter](https://github.com/Mind-Forge-AI/PonoLock/blob/v0.3.1/research/charter.md)
93
+
94
+ ## Honest limits
95
+
96
+ A common host clock, configured FPS, nearest-neighbour matching or visually aligned
97
+ previews do not prove exposure synchronization. Host receipt time follows exposure by an
98
+ unknown delay. HDOP and satellite count are not accuracy. Zero queue drops is not zero
99
+ device-side loss. Unknown uncertainty is recorded as unknown, never zero, and gaps are
100
+ never filled by interpolation.
101
+
102
+ PonoLock was motivated by data-integrity needs in the AfricaDrive dataset project and is
103
+ developed independently of it. Images, positions and credentials stay local; PonoLock has
104
+ no telemetry. MIT licensed.
@@ -0,0 +1,22 @@
1
+ # Security
2
+
3
+ Studio binds `127.0.0.1` by default. Authentication is entirely local. First-run setup
4
+ uses a one-time token delivered in a browser fragment (not a request URL), or an
5
+ interactive local CLI. No shipped passwords, cloud identity, analytics or uploads exist.
6
+
7
+ Password hashes use Argon2id. Browser sessions use random tokens stored hashed in
8
+ SQLite, absolute expiration, HttpOnly/SameSite=Strict cookies, CSRF checks and role
9
+ authorization. Login is limited per client. SQLite connections use parameterized values;
10
+ recording identifiers and file paths are constrained. The frontend has a self-only CSP.
11
+ HTTP loopback cookies deliberately omit Secure because the default transport is local
12
+ HTTP. Explicit remote access requires TLS certificate/key, secure cookies and
13
+ `--allow-remote`. Remote hosting has not been penetration-tested or deployed.
14
+
15
+ Operating-system access to the data directory permits account recovery and access to
16
+ recordings. Protect OS accounts, disks and backups accordingly. Account recovery revokes
17
+ existing sessions. Keep credentials, session cookies, setup fragments, images and location
18
+ logs out of issues, screenshots and public artifacts.
19
+
20
+ Report vulnerabilities privately to the repository maintainers using GitHub private
21
+ security reporting when available. Include a minimal reproduction without private data.
22
+ Do not disclose live credentials or tokens in a public issue.
@@ -0,0 +1,13 @@
1
+ """Run independently reproducible scaling conditions; compare artifacts across runs."""
2
+
3
+ from pathlib import Path
4
+
5
+ from ponolock.benchmarks import SyntheticConfig, run_benchmark
6
+
7
+ if __name__ == "__main__":
8
+ for count in (1, 2, 4, 8):
9
+ result = run_benchmark(
10
+ SyntheticConfig(sensor_count=count, seed=42),
11
+ Path("artifacts/scalability") / f"cameras_{count}",
12
+ )
13
+ print(count, result["resources"])