diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7a27614 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +build/ +*.aux +*.log +*.out diff --git a/OUTLINE.md b/OUTLINE.md index 2ee78f8..2d7ab26 100644 --- a/OUTLINE.md +++ b/OUTLINE.md @@ -122,7 +122,7 @@ Keep the structure required by `agents/paper.md` and `OKF_Vault/mission/paper.md - [x] Live app/API URLs, image sizes, plan latency. - [x] Author name and ORCID (Noel Sabia); affiliation intentionally blank. - [x] Code release timing documented (after the hackathon). -- [ ] Plan figure with raw screenshot (current figure is a print reconstruction), cold deployment time. +- [ ] Plan figure with raw screenshot (current figure is a print reconstruction); cold deployment time documented as not measured. - [ ] Figure generation — use the real CSV; no synthetic data in the paper. - [ ] Author names/affiliation for the Zenodo record. - [ ] Decision: Version A only, Version B only, or both. diff --git a/PulseCast-Extended-Paper.pdf b/PulseCast-Extended-Paper.pdf new file mode 100644 index 0000000..e0b1d0f Binary files /dev/null and b/PulseCast-Extended-Paper.pdf differ diff --git a/PulseCast-Hackathon-Report.pdf b/PulseCast-Hackathon-Report.pdf new file mode 100644 index 0000000..e3d4d1d Binary files /dev/null and b/PulseCast-Hackathon-Report.pdf differ diff --git a/README.md b/README.md index c9a7f7e..71e22c5 100644 --- a/README.md +++ b/README.md @@ -4,31 +4,35 @@ Two versions of the paper, plus the research trail. | File | What it is | Status | |---|---|---| -| `main.md` | Version A — 4–5 page hackathon technical report | Draft; ~3,600 words, 5 figures, 4 tables | -| `main-extended.md` | Version B — 10–12 page Zenodo paper | Draft; ~10,000 words, 44 references | +| `PulseCast-Hackathon-Report.pdf` | Upload-ready 4-page A4 hackathon report | Final draft | +| `PulseCast-Extended-Paper.pdf` | Upload-ready 11-page A4 Zenodo paper | Final draft | +| `main.md` | Markdown source for the hackathon report | Final draft | +| `main-extended.md` | Markdown source for the extended paper | Final draft | +| `ZENODO.md` | Copy-paste Zenodo metadata and upload checklist | Ready | | `references.md` | Canonical reference list and verification checklist | Draft | | `OUTLINE.md` | Writing plan, claims/non-claims, figures/tables | Working document | -| `figures/` | Generated figures used by both versions | Draft figures | -| `research/` | Research notes (code audit, privacy law, sensing, heatmap, PETs, applications, data quality) | Complete | +| `figures/` | Generated figures used by both versions | Final | +| `research/` | Research notes (code audit, privacy law, sensing, heatmap, PETs, applications, data quality) | Private; do not upload | +| `build/` | HTML/CSS/PDF build artifacts | Working files | ## Build -There is no Pandoc/LaTeX in this workspace. Render with any Markdown-to-PDF tool, or use a two-column template. Figure paths are relative to `paper/`: +The upload-ready PDFs were generated from Markdown via `marked` and headless Chrome with `build/style.css` (A4; 4 pages for the short report, 11 pages for the extended paper). `build/` is a working directory, not an upload artifact. Figure paths are relative to the repository root: ```text -paper/figures/fig_sensor_map.png -paper/figures/fig_hourly_profile.png -paper/figures/fig_quantization.png -paper/figures/fig_architecture.png -paper/figures/fig_plan.png -paper/figures/fig_forecast.png +figures/fig_sensor_map.png +figures/fig_hourly_profile.png +figures/fig_quantization.png +figures/fig_architecture.png +figures/fig_plan.png +figures/fig_forecast.png ``` `fig_plan.png` is a print reconstruction of the live plan screen for `scenario=sunny-saturday-market`, `standard=standard` (live API query, 14 Nov 2026; values: 5 peak staff, 172 staff-hours, €2,752, 100% coverage, €5,600 flat schedule). Replace it with the raw screenshot file if you prefer the exact pixels. ## Verification status -- Numbers: checked against `OKF_Vault/mission/data.md`, the generated `metrics.json`, and `paper/research/07-data-quality.md`. +- Numbers: checked against `OKF_Vault/mission/data.md`, the generated `metrics.json`, and `research/07-data-quality.md`. - Canonical metrics: production 7-day **3.32 / 27.5% / 0.777**; day-ahead weather **3.36 / 27.8% / 0.763**; seasonal naive **5.40 / 44.7% / 0.462**. The mission brief’s 3.36/27.8/0.779 was the quick baseline; the paper explains the difference once. - Deployment: live app https://pulse.noelsabia.dev; API https://api-pulse.noelsabia.dev. - v1.1 images: api 16.9 MB, web 249 MB, ml 952 MB. @@ -47,7 +51,7 @@ paper/figures/fig_forecast.png - [ ] Plan figure: currently reconstructed from the provided screenshot for print legibility. Replace with the raw screenshot file if you prefer the exact pixels. - [x] Code release timing documented (after the hackathon); public URL to be added then. - [x] Author name and ORCID (Noel Sabia, 0009-0008-3064-7573); affiliation intentionally blank. -- [ ] Cold deployment time. +- [x] Cold deployment time documented as not measured. - [ ] Replace internal project-note citations with public artifacts if a venue requires it. - [ ] Final page-count trim for Version A if a strict 4–5 page limit applies. diff --git a/ZENODO.md b/ZENODO.md new file mode 100644 index 0000000..575be0e --- /dev/null +++ b/ZENODO.md @@ -0,0 +1,79 @@ +# Zenodo upload sheet + +Do **not** publish until the author confirms. This file is copy-paste metadata for the two paper records. The research notes are private and must not be uploaded. + +## Record A — hackathon report + +**File:** `PulseCast-Hackathon-Report.pdf` (4 pages, A4) + +**Title:** PulseCast: Turning a Noisy Footfall Index into a Weekly Staffing Plan + +**Authors:** Noel Sabia (ORCID 0009-0008-3064-7573) + +**Resource type:** Publication → Report → Technical report + +**Publication date:** 2026-11-14 + +**Version:** 1.0 + +**Language:** English + +**License:** CC BY 4.0 + +**Description:** +> A 4-page technical report on PulseCast, a decision-first staffing copilot built on eight passive Bluetooth footfall counters in a ~580 m × 280 m inner-city cluster in Heilbronn, Germany. The system fuses five months of 15-minute device counts with Open-Meteo weather and Baden-Württemberg public holidays, trains a global gradient-boosted model on a time-based split, and converts the forecast into a weekly shift plan through a transparent staffing heuristic. On a 28-day holdout, the production 7-day model reaches MAE 3.32, WAPE 27.5%, and R² 0.777 versus 5.40, 44.7%, and 0.462 for a seasonal-naive baseline; the day-ahead model reaches 3.36, 27.8%, and 0.763. The report also documents a code-level audit showing that the published value is a short-window count of randomized BLE addresses scaled by 0.7, not a 15-minute count of people. The v1.1 deployment handles 120/120 concurrent SSE clients with zero errors and a p95 event latency of 331 ms. +> +> AI tools were used for drafting and editing. The author checked each number and citation; some sources are project documentation or estimates. + +**Keywords:** footfall forecasting; PAX counter; Bluetooth Low Energy; staffing; decision support; smart cities; STACKIT; SKE; Nuxt; Go; FastAPI + +**Related identifiers:** +- Is supplemented by / is documented by: `https://pulse.noelsabia.dev` (live app) +- Is supplemented by: `https://api-pulse.noelsabia.dev` (API) +- References: the extended paper (add DOI after upload) +- Code: released after the hackathon (add URL when available) + +## Record B — extended paper + +**File:** `PulseCast-Extended-Paper.pdf` (11 pages, A4) + +**Title:** The Pulse Is Not the People: A Code-Level Audit of Bluetooth Footfall Sensing and a Privacy-First Architecture for Urban Decisions + +**Authors:** Noel Sabia (ORCID 0009-0008-3064-7573) + +**Resource type:** Publication → Preprint + +**Publication date:** 2026-11-14 + +**Version:** 1.0 + +**Language:** English + +**License:** CC BY 4.0 + +**Description:** +> An extended technical paper that audits the “privacy-preserving footfall” claim on the eight-sensor PAX counter network in Heilbronn. The public 2026 firmware (commit e8be8bf) implements a ~10-second passive BLE scan, a 16-bit dedup key, a 0.7 multiplier, and a 900-second sleep; the deployed 2025 binary may differ, and the data confirm the 0.7 scaling and per-wake export, not the scan duration or truncation. In the 12 June model window (83,156 values), all values are exact multiples of 0.7; the 18 June coverage panel (82,170 readings) has all eight sensors in only 28.2% of 15-minute slots. The paper analyzes the GDPR/ePrivacy/TDDDG status of MAC-based sensing, proposes a privacy-first sensing and PET stack, develops a network-aware hierarchical heatmap and quantile forecast, and maps the decision-grade contract across the six hackathon challenges: direct for staffing, analytical for advertising, conditional for waste routing, sibling for sensor placement and LoRaWAN planning, and not applicable to sentiment or the learning guide. +> +> AI tools were used for drafting and editing. The author checked each number and citation; the legal analysis is a research draft, not legal advice, and some sources are guidance, DPA positions, or inferences rather than binding law. + +**Keywords:** Bluetooth LE; PAX counter; MAC randomization; privacy; GDPR; TDDDG; ePrivacy; differential privacy; spatiotemporal forecasting; urban sensing; decision support + +**Related identifiers:** +- Is supplemented by: `https://pulse.noelsabia.dev` (live app) +- Is supplemented by: `https://api-pulse.noelsabia.dev` (API) +- References: the hackathon report (add DOI after upload) +- Code: released after the hackathon (add URL when available) + +## Do not upload + +- `research/` notes (private; not part of the final paper). +- The raw challenge CSV (not redistributed). +- The `Paper/` git metadata. +- Any local kubeconfig, token, or credential file. + +## After the hackathon + +- Code record: `PulseCast v1.1` — Software; license TBD (MIT/Apache-2.0). +- Derived-data record: metrics, aggregates, figure data — Dataset; CC BY 4.0 or CC0; only if the organizers permit. +- Link the records with related identifiers; cite the **version DOI** for exact reproducibility and the **concept DOI** for the latest version. +- Check the final PDFs for the latest numbers before publishing; do not publish the v1.0 k6 baseline as the result. diff --git a/main-extended.md b/main-extended.md index c9c9561..2d7adf0 100644 --- a/main-extended.md +++ b/main-extended.md @@ -432,7 +432,7 @@ A paper that reports these tests, even if some fail, is stronger than one that a Measured on v1.1: 120/120 SSE connections opened and closed, zero connection errors, p95 event latency 331 ms, p95 scenario latency 646 ms, presenter POST 49.60 ms, over 4m57.9s; plan generation 19 ms cold (contract < 2 s); images 16.9 MB (api), 249 MB (web), 952 MB (ml). Remaining checks: -- cold deployment time `[TODO]`; +- cold deployment time not measured; - failure drills: FastAPI down, Open-Meteo down, tunnel down, pod restart; - observability: health/ready, data/model versions, staleness labels; - a repeat of the 120-client run after any image or cluster change. diff --git a/main.md b/main.md index 59b0d36..4fb2b01 100644 --- a/main.md +++ b/main.md @@ -159,9 +159,9 @@ Per-sensor errors vary (Table 3): Stadtgalerie has the highest MAE (5.83); Hagen | Presenter POST latency | 49.60 ms | | Duration | 4m57.9s | | Image sizes (api / web / ml) | 16.9 MB / 249 MB / 952 MB | -| Cold deployment time | `[TODO]` | +| Cold deployment time | not measured | -*Table 4. System metrics from the v1.1 deployment and the v1.1 120-client Cloudflare k6 run. Cold deployment time is still `[TODO]`.* +*Table 4. System metrics from the v1.1 deployment and the v1.1 120-client Cloudflare k6 run. Cold deployment time was not measured.* The v1.1 120-client Cloudflare run is the measured result: 120/120 connections opened and closed, zero errors, p95 event 331 ms. The plan screen compares the recommended schedule to a flat schedule on coverage and cost under stated assumptions; this is a heuristic comparison, not an ROI claim.