Reproducible real-world testing for Bitchat.
Current dataset: No real field-test sessions have been contributed yet.
Bitchat Field Test defines how to collect and report bounded Bitchat field observations. It turns versioned protocols, physical devices, environmental context, intended topology, and raw observations into inspectable records and reproducible reports. The methodology exists now; empirical findings do not.
The project is independent. It is not affiliated with, endorsed by, or maintained by Bitchat, Permissionless Technologies, or any upstream maintainer.
A session records contributor-declared observations under documented conditions: within-window message outcomes, late delivery, visible evidence, versions, app/screen/process/power state, evidenced internet/Nostr state, measured or estimated distance, obstacles, intended topology, and optional privacy-reviewed attachments. Code derives an evaluable within-window proportion without counting unknown outcomes as failures, and calculates timing medians separately by method and target event.
It does not produce a Bitchat ranking, reliability certification, recommendation, security audit, universal range, global latency claim, or overall quality score. Physical placement is never treated as proof of a route. A successful delivery is never treated as proof of BLE, Nostr, Wi-Fi Aware, courier, or a specific hop count.
There are currently zero real Bitchat field-test sessions in results/. That is the current project state, not a missing placeholder. The production dashboard displays: “No real field-test sessions have been contributed yet.” Synthetic development records live only in fixtures/synthetic/, carry a mandatory warning, require explicit fixture mode, and are rejected by production loaders and dashboard builds.
Requirements: Node.js 20 or newer and a clean Git checkout.
npm ci
npm run bft -- init --protocol direct-baseline --protocol-version 1.1 --id <session-id>
# Follow protocols/direct-baseline/FIELD-CHECKLIST.md during the physical test.
npm run bft -- validate results/<session-id>/session.yamlbft init creates an observation-free draft; it does not insert a date, device, version, result, or measurement. The direct-baseline first-session checklist carries the tester through execution, privacy review, strict validation, report generation, and the final contribution gate.
| Protocol | Version | Purpose |
|---|---|---|
| Direct baseline | 1.1 | Two-device controlled baseline and first-session checklist |
| Distance progression | 1.0 | Documented near/middle/far positions |
| Obstacle comparison | 1.0 | Reference and obstacle conditions |
| Multi-peer topology | 1.0 | Three-or-more-device intended relay topology |
| Peer recovery | 1.0 | Baseline, peer removal, and recovery |
| Background behavior | 1.0 | Foreground, background, and locked states |
| Internet and Nostr behavior | 1.0 | Internet-state observations with transport-evidence boundaries |
Every protocol defines its objective, required devices, setup, controlled variables, procedure, required observations, stop conditions, limitations, and privacy considerations. Repeat counts are session conventions, not universal reliability thresholds.
Real records are YAML validated by schemas/session.schema.json and additional semantic rules in src/validation.ts. The top-level schema_version is currently "1". Major concepts remain separate:
- Pinned upstream evidence: categorized documentation/source context, not a field observation.
- Contributor-declared observation: a raw attempt outcome or directly/instrumentally observed event.
- Derived metric: code-calculated denominators, within-window proportions, and method/endpoint-specific timing summaries.
- Interpretation: optional tester-supplied conclusion.
Session-local device IDs such as device-a are required. Exact GPS, IMEI, serial number, phone number, username/account ID, Wi-Fi SSID/BSSID, Bluetooth address, advertising ID, peer key, and private key are neither required nor wanted.
bft init --protocol <id> --id <session-id>
bft validate <session.yaml> [--strict] [--json]
bft inspect <session.yaml> [--json]
bft summarize <session.yaml> [--json]
bft compare <session-a.yaml> <session-b.yaml> [--json]
bft report <session.yaml> [--output report.md | --stdout]
bft attachment-metadata <image> [--json]
compare exposes protocol/version, device/OS combinations, environment, distance, app/process states, timing methods/endpoints, and missing metadata. Incompatible protocols or sessions without evaluable outcomes do not receive a numeric difference. Compatible output is descriptive and never causal.
CLI exit codes are 0 for success, 1 for usage errors or invalid validation results, and 2 for operational errors. Ordinary errors do not print stack traces. Report output is restricted to Markdown inside the session directory.
Markdown reports contain distinct Observed Results, Derived Metrics, Interpretation, Limitations, and Tester Notes sections. Raw attempt evidence stays visible behind the summary.
The static dashboard reads only validated sessions from results/*/session.yaml and requires no database, account, backend, or paid credentials:
npm run build:dashboard
npx serve siteIt shows counts, represented protocols, versions, platforms, voluntary location granularity, filters, per-session evidence, and links to copied raw YAML and Markdown. It deliberately does not compute a global delivery percentage.
CI validates schemas, protocols, CLI behavior, exact result paths, four explicit human attestations, generated-report consistency, synthetic isolation, and the static build. CI can establish internal consistency; it cannot prove that physical devices were used or that a contributor was honest. The attestations are declarations, not cryptographic proof.
npm ci
npm run generate:schemas
npm run lint
npm run typecheck
npm test
npm run validate:protocols
npm run validate:results
npm run buildCore use is local-first and idle infrastructure cost is effectively zero. A static host such as GitHub Pages is the recommended deployment target. The methodology, records, CLI, and reports remain useful without any dashboard deployment or upstream acknowledgement.
This repository is licensed under Apache-2.0. That license applies only to Bitchat Field Test materials and code; it does not relicense Bitchat or imply any upstream relationship.