[codex] Add FlowRouter V0 POC hardware package

docs/DECISIONS/0001-flowrouter-v0-scope.md

@@ -0,0 +1,35 @@
+# Decision 0001: FlowRouter V0 Scope
+
+Date: 2026-05-13
+
+## Status
+
+Accepted for V0 research package.
+
+## Context
+
+FlowRouter needs to be concrete enough for hardware, dashboard, services, and field-test agents to share packet shapes and operational assumptions. It also needs strict boundaries so the project does not overclaim internet replacement, production manufacturing, hardware trustlessness, appchain operation, or LoRa bandwidth.
+
+## Decision
+
+FlowRouter V0 is a production-shaped proof-of-concept package built around certified commodity router/radio hardware, Raspberry Pi or mini PC compute, NVMe/local cache, Meshtastic/LoRa control signaling, NFC Memory Cartridge metadata, FlowCore light-pipe status, local dashboard feeds, simulator packets, and controlled field-test plans.
+
+V0 packet schemas and simulator outputs are advisory interfaces for later consumers. They are not production protocol commitments.
+
+## Boundaries
+
+- No ISP replacement claim.
+- No broadband over LoRa/Meshtastic.
+- No custom RF board or antenna design.
+- No production manufacturing commitment.
+- No passive income promise.
+- No full trustlessness claim.
+- No production L1/appchain operation.
+- No validator or data availability role for hardware nodes.
+- No final CAD until physical measurements are sufficient.
+
+## Consequences
+
+- Hardware work can advance through docs, schemas, fixtures, simulator output, and field-test plans before physical CAD.
+- Future services and dashboards can consume deterministic sample feeds without depending on hardware availability.
+- Hardware security assumptions remain conservative: physical tampering, spoofing, replay, unauthenticated messages, sidecar bandwidth limits, power/thermal risk, storage failure, and operator key exposure are in scope.

docs/SECURITY_MODEL.md

@@ -117,6 +117,16 @@ Live V0 registries and schedulers are commitment surfaces, not complete trust sy
 - Physical tampering
 - Unsafe power or enclosure assumptions
 - Overestimating LoRa or Meshtastic bandwidth
+- Treat FlowRouter v0 devices as physically exposed research rigs until a later identity and attestation model exists.
+- Keep hardware control surfaces local-only by default, and require explicit authentication before any radio message changes local state.
+- Treat local caches as stale or replayable unless entries are checked against commitments, receipts, or other verifiable provenance.
+- Avoid custom RF, antenna, amplifier, and production enclosure assumptions in v0; use certified commodity hardware within local radio rules.
+- Treat replayed LoRa messages as expected adversarial input until sequence, nonce, freshness, and audit rules exist.
+- Treat FCC, regional radio, antenna, duty-cycle, and equipment-authorization mistakes as project risks, not just operator mistakes.
+- Treat power, brownout, thermal throttling, fan failure, and sealed-enclosure heat buildup as safety and data-integrity risks.
+- Treat NVMe, SD card, and removable cartridge failures as cache-integrity risks; local cache is not a permanent source of truth.
+- Treat operator keys, channel keys, dashboard credentials, and cartridge labels as sensitive operational material that must not be exposed on displays, NFC tags, logs, or public MQTT.
+- Treat simulator packets, packet schemas, and generated fixtures as unsigned advisory test data until a later identity and authentication design exists.
 
 ### Supply Chain
 

hardware/README.md

@@ -0,0 +1,53 @@
+# FlowMemory Hardware
+
+Last updated: 2026-05-13
+
+This directory contains the FlowRouter V0 proof-of-concept hardware package. It is production-shaped but research-safe: the docs, schemas, simulator, and field-test plans are intended to help later dashboard, services, and hardware work consume consistent data without claiming finished hardware.
+
+## Package Map
+
+- `flowrouter/`: FlowRouter V0 scope, BOM, assembly, enclosure, light-pipe, printing, and measurement docs.
+- `lora-sidecar/`: Meshtastic/LoRa role, compact control-message inventory, and two-node demo notes.
+- `memory-cartridges/`: NFC Memory Cartridge concept and metadata boundaries.
+- `simulator/`: deterministic FlowRouter POC packet generator and schema validator.
+- `fixtures/`: generated sample packet feeds for tests and future dashboard/service consumers.
+- `field-tests/`: field-test plans and logs for controlled hardware experiments.
+
+## V0 Purpose
+
+FlowRouter V0 is a local FlowMemory gateway POC. It can model or test:
+
+- Local node status.
+- Artifact cache status.
+- Compact receipt relay.
+- Heartbeat messages.
+- Gateway discovery.
+- Local dashboard feed shape.
+- Meshtastic/LoRa sidecar status and limits.
+- NFC Memory Cartridge metadata.
+- FlowCore light-pipe status.
+- Enclosure measurement direction.
+
+## V0 Non-Goals
+
+FlowRouter V0 does not:
+
+- Replace ISPs.
+- Create global internet from nothing.
+- Carry broadband over LoRa or Meshtastic.
+- Move model weights, large artifacts, media, or raw memory payloads over LoRa.
+- Prove hardware trustlessness.
+- Mine tokens or promise passive income.
+- Run a production L1 or appchain.
+- Define production manufacturing, final CAD, or custom RF boards.
+
+## Validation Entry Point
+
+Generate and validate deterministic simulator output:
+
+```powershell
+python hardware/simulator/flowrouter_sim.py --seed 42 --out hardware/fixtures/flowrouter_sample_seed42.json
+python hardware/simulator/flowrouter_sim.py --validate-file hardware/fixtures/flowrouter_sample_seed42.json
+```
+
+The simulator uses only the Python standard library.

hardware/field-tests/README.md

@@ -0,0 +1,18 @@
+# FlowRouter Field Tests
+
+Last updated: 2026-05-13
+
+Field tests must stay controlled, reversible, and honest about limitations. The current package includes a two-node Meshtastic plan and simulator-generated packet fixtures for dry runs before hardware is attached.
+
+## Rules
+
+- Use certified router and radio hardware.
+- Set the correct LoRa region before transmit.
+- Keep public MQTT disabled unless a test explicitly requires and documents a private broker posture.
+- Do not send secrets, large artifacts, model data, media, or raw memory over LoRa.
+- Do not claim ISP replacement, production mesh, passive income, full trustlessness, or emergency-service reliability.
+- Stop on thermal, power, radio-region, interference, or secret-exposure concerns.
+
+## Plans
+
+- `TWO_NODE_MESHTASTIC_FIELD_TEST.md`: two-node heartbeat, discovery, digest, dashboard, and offline-mode plan.

hardware/field-tests/TWO_NODE_MESHTASTIC_FIELD_TEST.md

@@ -0,0 +1,85 @@
+# Two-Node Meshtastic Field Test
+
+Last updated: 2026-05-13
+
+This plan covers issues #12 and #33 and uses the simulator outputs from `../simulator/` as dry-run packet fixtures before radio transmission.
+
+## Objective
+
+Validate that two FlowRouter-like nodes can exchange compact advisory control packets over Meshtastic while normal FlowMemory data remains on WiFi/Ethernet.
+
+## Hardware
+
+Node A:
+
+- Certified OpenWrt router or lab LAN gateway.
+- Raspberry Pi 5 or mini PC.
+- NVMe/local cache candidate.
+- Meshtastic sidecar in the correct regional variant.
+
+Node B:
+
+- Laptop, Raspberry Pi, or second FlowRouter-like node.
+- Meshtastic sidecar in the same region/channel settings.
+
+## Dry Run
+
+Before using radios:
+
+```powershell
+python hardware/simulator/flowrouter_sim.py --seed 42 --out hardware/fixtures/flowrouter_sample_seed42.json
+python hardware/simulator/flowrouter_sim.py --validate-file hardware/fixtures/flowrouter_sample_seed42.json
+```
+
+Review the generated heartbeat, gateway discovery, receipt relay, cache status, sidecar status, dashboard feed, and failure/offline packet.
+
+## Radio Setup
+
+- Confirm region and frequency variant.
+- Attach antennas before transmit.
+- Record firmware version, modem preset, hop limit, channel name, and MQTT settings.
+- Prefer private channel settings.
+- Keep public MQTT disabled by default.
+- Keep operator command warning packets non-executing.
+
+## Test Sequence
+
+1. Baseline both nodes on normal LAN/internet.
+2. Send node heartbeat from Node A.
+3. Send gateway discovery from Node A.
+4. Send local cache status digest from Node A.
+5. Send compact receipt relay from Node A.
+6. Disable upstream internet for Node A.
+7. Confirm local dashboard feed still reports LAN-local state.
+8. Send emergency/offline signal from Node A.
+9. Restore upstream internet.
+10. Record reconciliation notes and operator confusion points.
+
+## Success Criteria
+
+- Node B receives heartbeat and gateway discovery packets.
+- Digest and receipt packets fit the compact schema.
+- Offline/failure packet is distinguishable from verified state.
+- No heavy payload or secret crosses LoRa.
+- Operators can explain local, advisory, and verified status.
+
+## Metrics
+
+- Packet count sent/received.
+- RSSI/SNR if available.
+- Hop count.
+- Delay observations.
+- Duplicate/lost packets.
+- Node A upstream outage detection time.
+- Local dashboard availability.
+- Cache status before/during/after outage.
+- Sidecar temperature and power notes if available.
+
+## Stop Conditions
+
+- Wrong region, antenna, or transmit configuration.
+- Suspected harmful interference.
+- Thermal or power instability.
+- Secret, credential, channel key, model data, media, raw memory, or large artifact appears in a payload.
+- Operator command warning starts to execute privileged behavior.
+- Public MQTT exposure is discovered unexpectedly.