Initial: WASM sensor stack — core types, MCU module (32KB), WIT contract

.gitignore

@@ -0,0 +1,3 @@
+/target/
+result
+.direnv/

Cargo.lock

@@ -0,0 +1,153 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "byteorder"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "dlmalloc"
+version = "0.2.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f5b01c17f85ee988d832c40e549a64bd89ab2c9f8d8a613bdf5122ae507e294"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "hash32"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47d60b12902ba28e2730cd37e95b8c9223af2808df9e902d4df49588d1470606"
+dependencies = [
+ "byteorder",
+]
+
+[[package]]
+name = "heapless"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bfb9eb618601c89945a70e254898da93b13be0388091d42117462b265bb3fad"
+dependencies = [
+ "hash32",
+ "stable_deref_trait",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.184"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
+
+[[package]]
+name = "minicbor"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0452a60c1863c1f50b5f77cd295e8d2786849f35883f0b9e18e7e6e1b5691b0"
+dependencies = [
+ "minicbor-derive",
+]
+
+[[package]]
+name = "minicbor-derive"
+version = "0.15.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bd2209fff77f705b00c737016a48e73733d7fbccb8b007194db148f03561fb70"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "synapse-core"
+version = "0.1.0"
+dependencies = [
+ "heapless",
+ "minicbor",
+]
+
+[[package]]
+name = "synapse-sensor"
+version = "0.1.0"
+dependencies = [
+ "dlmalloc",
+ "heapless",
+ "minicbor",
+ "synapse-core",
+]
+
+[[package]]
+name = "synapse-web"
+version = "0.1.0"
+dependencies = [
+ "minicbor",
+ "synapse-core",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]

Cargo.toml

@@ -0,0 +1,32 @@
+[workspace]
+resolver = "2"
+members = [
+    "crates/synapse-core",
+    "crates/synapse-sensor",
+    "crates/synapse-web",
+]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "AGPL-3.0-or-later"
+repository = "http://git.houston.local/robbo/synapse-wasm"
+authors = ["Robert David Adams III <robbo@synapseagriculture.com>"]
+
+[workspace.dependencies]
+# Shared across crates — pin versions here, inherit in members
+minicbor = { version = "0.25", features = ["alloc", "derive"] }  # CBOR serialization (tiny, no-std compatible)
+heapless = "0.8"          # Fixed-size collections for no-std (MCU-safe)
+
+# These only apply to std-capable targets (gateway, host, browser)
+# MCU crate uses no_std and doesn't pull these in
+[workspace.metadata.unused]
+# Placeholder — workspace.dependencies above are what matters
+
+[profile.release]
+# Aggressive optimization for WASM binary size
+opt-level = "z"       # Optimize for size over speed
+lto = true            # Link-time optimization across crate boundaries
+codegen-units = 1     # Single codegen unit = better optimization, slower compile
+panic = "abort"       # No unwinding = smaller binary (critical for MCU)
+strip = true          # Strip debug symbols from release builds

build.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# Synapse Agriculture — WASM build pipeline
+# Run from workspace root inside `nix develop`
+#
+# This script enforces the correct build ordering:
+#   1. Native tests (fastest feedback loop)
+#   2. WASM compilation (catches target-specific issues)
+#   3. Size profiling (validates MCU memory budget)
+#   4. Runtime validation (wasm3 / wasmtime)
+#
+# Each step gates the next — fail fast, don't waste time.
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+WASM_TARGET="wasm32-unknown-unknown"
+WASI_TARGET="wasm32-wasip1"
+SENSOR_WASM="target/${WASM_TARGET}/release/synapse_sensor.wasm"
+OPTIMIZED_WASM="target/wasm-opt/synapse_sensor.wasm"
+
+# MCU memory budget (RP2350: 520KB total SRAM)
+# wasm3 runtime: ~64KB, LoRa + HAL: ~48KB, heap: ~100KB
+# Leaves roughly 300KB for the WASM module binary
+MAX_WASM_SIZE_KB=300
+
+step() { echo -e "\n${CYAN}═══ $1 ═══${NC}\n"; }
+pass() { echo -e "${GREEN}  ✓ $1${NC}"; }
+fail() { echo -e "${RED}  ✗ $1${NC}"; exit 1; }
+warn() { echo -e "${YELLOW}  ⚠ $1${NC}"; }
+
+# ── Step 1: Native tests ──────────────────────────────────────────────────
+# Run all tests on the host architecture (x86_64).
+# This validates shared types, calibration math, CBOR serialization,
+# and ASCII parsing WITHOUT any WASM complexity.
+# This is your fastest iteration loop — stay here until green.
+
+step "Step 1: Native tests (all crates)"
+cargo test --workspace --quiet 2>&1
+pass "All native tests passed"
+
+# ── Step 2: Compile sensor module to WASM ─────────────────────────────────
+# Target: wasm32-unknown-unknown (bare WASM, no WASI)
+# This is what runs on the MCU via wasm3.
+# cdylib crate-type in synapse-sensor produces the .wasm file.
+# release profile uses opt-level=z, LTO, panic=abort, strip=true
+# for minimum binary size.
+
+step "Step 2: Compile synapse-sensor → WASM (MCU target)"
+cargo build \
+    --package synapse-sensor \
+    --target "${WASM_TARGET}" \
+    --release \
+    --quiet 2>&1
+
+if [ ! -f "${SENSOR_WASM}" ]; then
+    fail "WASM binary not found at ${SENSOR_WASM}"
+fi
+
+RAW_SIZE=$(wc -c < "${SENSOR_WASM}")
+RAW_SIZE_KB=$((RAW_SIZE / 1024))
+pass "Raw WASM binary: ${RAW_SIZE_KB}KB (${RAW_SIZE} bytes)"
+
+# ── Step 3: Optimize for size ─────────────────────────────────────────────
+# wasm-opt from Binaryen does aggressive dead code elimination,
+# constant folding, and code deduplication. The -Oz flag optimizes
+# purely for size (vs -O4 which optimizes for speed).
+# This typically cuts Rust WASM binaries by 40-60%.
+
+step "Step 3: Size optimization (wasm-opt -Oz)"
+mkdir -p "$(dirname ${OPTIMIZED_WASM})"
+wasm-opt -Oz \
+    --strip-debug \
+    --strip-producers \
+    -o "${OPTIMIZED_WASM}" \
+    "${SENSOR_WASM}" 2>&1
+
+OPT_SIZE=$(wc -c < "${OPTIMIZED_WASM}")
+OPT_SIZE_KB=$((OPT_SIZE / 1024))
+SAVINGS=$(( (RAW_SIZE - OPT_SIZE) * 100 / RAW_SIZE ))
+pass "Optimized WASM: ${OPT_SIZE_KB}KB (${OPT_SIZE} bytes, ${SAVINGS}% reduction)"
+
+# ── Step 4: MCU memory budget check ──────────────────────────────────────
+# Hard gate: if the module exceeds the RP2350 memory budget, stop.
+# Better to catch this now than when flashing hardware in the field.
+
+step "Step 4: MCU memory budget check (max ${MAX_WASM_SIZE_KB}KB)"
+if [ "${OPT_SIZE_KB}" -gt "${MAX_WASM_SIZE_KB}" ]; then
+    fail "WASM module (${OPT_SIZE_KB}KB) exceeds MCU budget (${MAX_WASM_SIZE_KB}KB)"
+    echo "  Run: twiggy top ${OPTIMIZED_WASM}"
+    echo "  to find what's taking space"
+    exit 1
+fi
+pass "Module fits in MCU budget: ${OPT_SIZE_KB}KB / ${MAX_WASM_SIZE_KB}KB"
+
+# ── Step 5: Size profiling ────────────────────────────────────────────────
+# Even if we're under budget, know where the bytes are going.
+# twiggy shows the top functions by size — if serde or fmt
+# machinery snuck in, you'll see it here.
+
+step "Step 5: Size profile (top 15 largest items)"
+if command -v twiggy &>/dev/null; then
+    twiggy top "${OPTIMIZED_WASM}" -n 15 2>&1 || warn "twiggy failed (non-fatal)"
+else
+    warn "twiggy not found — skip size profiling"
+fi
+
+# ── Step 6: WASM validation ──────────────────────────────────────────────
+# wasm-tools validate checks the module against the WASM spec.
+# Catches issues like invalid opcodes, type mismatches, or
+# features the MCU runtime doesn't support.
+
+step "Step 6: WASM module validation"
+if command -v wasm-tools &>/dev/null; then
+    wasm-tools validate "${OPTIMIZED_WASM}" 2>&1
+    pass "Module passes WASM spec validation"
+else
+    warn "wasm-tools not found — skip validation"
+fi
+
+# ── Step 7: Export inspection ─────────────────────────────────────────────
+# Verify the module exports the expected guest functions.
+# The wasm3 runtime on the MCU will look for these by name.
+
+step "Step 7: Export verification"
+if command -v wasm-tools &>/dev/null; then
+    EXPORTS=$(wasm-tools dump "${OPTIMIZED_WASM}" 2>/dev/null | grep -c "export" || echo "0")
+    echo "  Module has ${EXPORTS} exports"
+
+    # Check for our required guest functions
+    for func in guest_init guest_sample guest_reconfigure; do
+        if wasm2wat "${OPTIMIZED_WASM}" 2>/dev/null | grep -q "\"${func}\""; then
+            pass "Found export: ${func}"
+        else
+            fail "Missing required export: ${func}"
+        fi
+    done
+else
+    warn "wasm-tools not found — skip export check"
+fi
+
+# ── Step 8: Import verification ───────────────────────────────────────────
+# Verify the module imports match what the MCU host firmware provides.
+# Any import the host doesn't implement = crash at instantiation.
+
+step "Step 8: Import verification (host function dependencies)"
+if command -v wabt &>/dev/null && command -v wasm2wat &>/dev/null; then
+    echo "  Required host functions:"
+    wasm2wat "${OPTIMIZED_WASM}" 2>/dev/null \
+        | grep '(import' \
+        | sed 's/.*"\([^"]*\)".*/    → \1/' \
+        || warn "Could not extract imports"
+else
+    warn "wabt not found — skip import check"
+fi
+
+# ── Summary ───────────────────────────────────────────────────────────────
+step "BUILD COMPLETE"
+echo -e "  ${GREEN}Native tests:   PASS${NC}"
+echo -e "  ${GREEN}WASM compile:   PASS${NC}"
+echo -e "  ${GREEN}Size budget:    ${OPT_SIZE_KB}KB / ${MAX_WASM_SIZE_KB}KB${NC}"
+echo -e "  ${GREEN}Spec valid:     PASS${NC}"
+echo ""
+echo "  Artifacts:"
+echo "    Raw:       ${SENSOR_WASM}"
+echo "    Optimized: ${OPTIMIZED_WASM}"
+echo ""
+echo "  Next steps:"
+echo "    wasmtime (WASI):  needs wasm32-wasip1 target build"
+echo "    wasm3 (MCU sim):  wasm3 ${OPTIMIZED_WASM} --func guest_sample"
+echo "    Browser:          trunk serve crates/synapse-web"
+echo ""

crates/synapse-core/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "synapse-core"
+description = "Shared types and calibration logic for the Synapse sensor stack"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[features]
+default = ["std"]
+std = ["minicbor/std"]
+# no default features = no_std (MCU target)
+# The MCU crate depends on synapse-core with default-features = false
+
+[dependencies]
+minicbor = { workspace = true }
+heapless = { workspace = true }

crates/synapse-core/src/lib.rs

@@ -0,0 +1,387 @@
+// Synapse Agriculture — Core Types
+//
+// These types are the Rust-native mirror of wit/sensor.wit.
+// They exist so that crates which DON'T use the component model
+// (like synapse-web for the browser) can still share the same
+// data structures without pulling in wit-bindgen.
+//
+// Rule: if you change a type here, the WIT file must change too,
+// and vice versa. They are two representations of one contract.
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+extern crate alloc;
+use alloc::vec::Vec;
+use minicbor::{Decode, Encode};
+
+// ---------------------------------------------------------------------------
+// Measurement units — what physical quantity a reading represents
+// ---------------------------------------------------------------------------
+
+/// Maps 1:1 to the measurement-unit enum in sensor.wit.
+/// The u8 repr keeps CBOR encoding to a single byte.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Encode, Decode)]
+#[cbor(index_only)]
+pub enum MeasurementUnit {
+    // Water chemistry
+    #[n(0)]  Ph,
+    #[n(1)]  Ec,
+    #[n(2)]  DissolvedOxygen,
+    #[n(3)]  Orp,
+    #[n(4)]  TemperatureWater,
+
+    // Soil
+    #[n(10)] MoistureVwc,
+    #[n(11)] TemperatureSoil,
+
+    // Atmosphere
+    #[n(20)] TemperatureAir,
+    #[n(21)] Humidity,
+    #[n(22)] Pressure,
+    #[n(23)] LightLux,
+    #[n(24)] LightPar,
+
+    // Power (Layer 7)
+    #[n(30)] Voltage,
+    #[n(31)] Current,
+    #[n(32)] Power,
+    #[n(33)] BatterySoc,
+}
+
+// ---------------------------------------------------------------------------
+// Reading quality — self-diagnostic assessment
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Encode, Decode)]
+#[cbor(index_only)]
+pub enum ReadingQuality {
+    #[n(0)] Good,
+    #[n(1)] Degraded,
+    #[n(2)] CalNeeded,
+    #[n(3)] Fault,
+}
+
+// ---------------------------------------------------------------------------
+// Core reading type — one sensor measurement with full provenance
+// ---------------------------------------------------------------------------
+
+/// A single sensor reading. This is the atomic unit of data in Synapse.
+/// Everything upstream (InfluxDB, Grafana, Board agents) consumes these.
+///
+/// Design decision: s32 fixed-point instead of f32.
+/// On Cortex-M0+/M33 without FPU, soft-float is ~10x slower than integer
+/// math. pH 7.23 is stored as 7230 (value * 1000). Calibration formulas
+/// use integer multiply-then-divide to stay in s32 throughout.
+/// The browser and host can convert to f64 for display.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub struct Reading {
+    /// Unix timestamp in milliseconds
+    #[n(0)] pub timestamp_ms: u64,
+    /// Sensor channel (physical probe identifier on this node)
+    #[n(1)] pub channel: u8,
+    /// Raw ADC/digital value before calibration
+    #[n(2)] pub raw_value: i32,
+    /// Calibrated value, fixed-point * 1000
+    #[n(3)] pub calibrated_value: i32,
+    /// What this reading measures
+    #[n(4)] pub unit: MeasurementUnit,
+    /// Self-diagnostic quality flag
+    #[n(5)] pub quality: ReadingQuality,
+}
+
+// ---------------------------------------------------------------------------
+// Calibration — linear two-point cal coefficients
+// ---------------------------------------------------------------------------
+
+/// Linear calibration: calibrated = (raw * slope / 1000) + offset
+/// Slope and offset are both fixed-point * 1000.
+///
+/// Example: pH probe reads raw 1650 at pH 7.0 and raw 2200 at pH 4.0.
+///   slope = (4000 - 7000) / (2200 - 1650) = -3000 / 550 ≈ -5454
+///   offset = 7000 - (1650 * -5454 / 1000) = 7000 + 8999 = 15999
+///   calibrate(1650) = (1650 * -5454 / 1000) + 15999 = -9000 + 15999 = 6999 ≈ 7.0 ✓
+///   calibrate(2200) = (2200 * -5454 / 1000) + 15999 = -11999 + 15999 = 4000 ≈ 4.0 ✓
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Encode, Decode)]
+pub struct Calibration {
+    #[n(0)] pub slope: i32,
+    #[n(1)] pub offset: i32,
+}
+
+impl Calibration {
+    /// Apply this calibration to a raw reading.
+    /// All arithmetic stays in i32 — no floating point needed.
+    /// The intermediate multiply uses i64 to prevent overflow
+    /// (raw up to ~2M * slope up to ~100K = fits in i64 fine).
+    pub fn apply(&self, raw: i32) -> i32 {
+        let intermediate = (raw as i64) * (self.slope as i64) / 1000;
+        (intermediate as i32) + self.offset
+    }
+
+    /// Identity calibration — passes raw through unchanged.
+    /// Used as default when no cal data exists yet.
+    pub const fn identity() -> Self {
+        Self {
+            slope: 1000,  // 1.0 in fixed-point
+            offset: 0,
+        }
+    }
+
+    /// Construct calibration from two known reference points.
+    /// (raw1, known1) and (raw2, known2), all in fixed-point * 1000.
+    /// Returns None if the two raw values are identical (divide by zero).
+    pub fn from_two_point(raw1: i32, known1: i32, raw2: i32, known2: i32) -> Option<Self> {
+        let raw_diff = raw2 - raw1;
+        if raw_diff == 0 {
+            return None;
+        }
+        // slope = (known2 - known1) * 1000 / (raw2 - raw1)
+        let slope = ((known2 as i64 - known1 as i64) * 1000) / raw_diff as i64;
+        // offset = known1 - (raw1 * slope / 1000)
+        let offset = known1 as i64 - (raw1 as i64 * slope / 1000);
+        Some(Self {
+            slope: slope as i32,
+            offset: offset as i32,
+        })
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Sensor config — pushed from gateway to node
+// ---------------------------------------------------------------------------
+
+/// Configuration for a sensor node. Pushed from gateway via LoRa OTA
+/// or set at initial provisioning. Serialized as CBOR for LoRa transport.
+#[derive(Debug, Clone, Encode, Decode)]
+pub struct SensorConfig {
+    /// How often to sample, in seconds
+    #[n(0)] pub sample_interval_secs: u32,
+    /// Bitmask of active channels (bit 0 = channel 0, etc.)
+    #[n(1)] pub active_channels: u8,
+    /// Per-channel calibration coefficients
+    /// Index in this vec = channel number
+    #[n(2)] pub calibrations: Vec<Calibration>,
+}
+
+impl SensorConfig {
+    /// Check if a specific channel is enabled in the bitmask
+    pub fn is_channel_active(&self, channel: u8) -> bool {
+        channel < 8 && (self.active_channels & (1 << channel)) != 0
+    }
+
+    /// Get calibration for a channel, falling back to identity if missing
+    pub fn cal_for(&self, channel: u8) -> Calibration {
+        self.calibrations
+            .get(channel as usize)
+            .copied()
+            .unwrap_or(Calibration::identity())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Transmission payload — what goes over LoRa
+// ---------------------------------------------------------------------------
+
+/// The complete payload for one LoRa transmission.
+/// Designed to fit in a single LoRa packet at SF7/BW125:
+///   Max payload = 242 bytes
+///   CBOR header + node_id + seq + battery ≈ 10 bytes
+///   Each Reading ≈ 18-22 bytes CBOR
+///   So roughly 10-12 readings per packet
+///
+/// If a node has more channels than fit in one packet,
+/// the module splits across multiple transmissions.
+#[derive(Debug, Clone, Encode, Decode)]
+pub struct TransmissionPayload {
+    /// Unique node ID within a site (set at provisioning)
+    #[n(0)] pub node_id: u16,
+    /// Monotonic sequence number — wraps at u16::MAX
+    /// Gateway uses this for dedup and gap detection
+    #[n(1)] pub sequence: u16,
+    /// Battery voltage in millivolts (power health monitoring)
+    #[n(2)] pub battery_mv: u16,
+    /// All readings from this sample cycle
+    #[n(3)] pub readings: Vec<Reading>,
+}
+
+// ---------------------------------------------------------------------------
+// MQTT topic builder — generates the Synapse topic namespace
+// ---------------------------------------------------------------------------
+
+/// Builds MQTT topic strings matching the Synapse namespace convention:
+///   synapse/site/{site}/zone/{zone}/node/{node_id}/reading
+///   synapse/site/{site}/zone/{zone}/node/{node_id}/health
+///   synapse/site/{site}/zone/{zone}/node/{node_id}/config
+///
+/// Only available with std feature (String requires alloc+std for formatting).
+/// The MCU doesn't build MQTT topics — the gateway does.
+#[cfg(feature = "std")]
+pub mod topics {
+    use alloc::format;
+    use alloc::string::String;
+
+    pub fn reading(site: &str, zone: &str, node_id: u16) -> String {
+        format!("synapse/site/{site}/zone/{zone}/node/{node_id}/reading")
+    }
+
+    pub fn health(site: &str, zone: &str, node_id: u16) -> String {
+        format!("synapse/site/{site}/zone/{zone}/node/{node_id}/health")
+    }
+
+    pub fn config(site: &str, zone: &str, node_id: u16) -> String {
+        format!("synapse/site/{site}/zone/{zone}/node/{node_id}/config")
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Conversion helpers for display layers (gateway, host, browser)
+// ---------------------------------------------------------------------------
+
+#[cfg(feature = "std")]
+impl Reading {
+    /// Convert fixed-point calibrated_value to f64 for display
+    pub fn calibrated_f64(&self) -> f64 {
+        self.calibrated_value as f64 / 1000.0
+    }
+
+    /// Human-readable unit string for dashboards
+    pub fn unit_str(&self) -> &'static str {
+        match self.unit {
+            MeasurementUnit::Ph => "pH",
+            MeasurementUnit::Ec => "µS/cm",
+            MeasurementUnit::DissolvedOxygen => "mg/L",
+            MeasurementUnit::Orp => "mV",
+            MeasurementUnit::TemperatureWater => "°C",
+            MeasurementUnit::MoistureVwc => "%",
+            MeasurementUnit::TemperatureSoil => "°C",
+            MeasurementUnit::TemperatureAir => "°C",
+            MeasurementUnit::Humidity => "%",
+            MeasurementUnit::Pressure => "hPa",
+            MeasurementUnit::LightLux => "lux",
+            MeasurementUnit::LightPar => "µmol/m²/s",
+            MeasurementUnit::Voltage => "mV",
+            MeasurementUnit::Current => "mA",
+            MeasurementUnit::Power => "mW",
+            MeasurementUnit::BatterySoc => "%",
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests — these run native on Houston, validating logic before WASM compile
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn identity_calibration_passes_through() {
+        let cal = Calibration::identity();
+        assert_eq!(cal.apply(1234), 1234);
+        assert_eq!(cal.apply(-500), -500);
+        assert_eq!(cal.apply(0), 0);
+    }
+
+    #[test]
+    fn two_point_calibration_ph() {
+        // pH 7.0 probe reads raw 1650, pH 4.0 reads raw 2200
+        let cal = Calibration::from_two_point(1650, 7000, 2200, 4000)
+            .expect("should not be None");
+
+        let ph7 = cal.apply(1650);
+        let ph4 = cal.apply(2200);
+
+        // Allow ±10 (0.01 pH) for integer rounding
+        assert!((ph7 - 7000).abs() < 10, "pH 7 cal: got {ph7}, expected ~7000");
+        assert!((ph4 - 4000).abs() < 10, "pH 4 cal: got {ph4}, expected ~4000");
+    }
+
+    #[test]
+    fn two_point_rejects_identical_raw() {
+        assert!(Calibration::from_two_point(100, 1000, 100, 2000).is_none());
+    }
+
+    #[test]
+    fn cbor_roundtrip_reading() {
+        let reading = Reading {
+            timestamp_ms: 1712345678000,
+            channel: 0,
+            raw_value: 1650,
+            calibrated_value: 7023,
+            unit: MeasurementUnit::Ph,
+            quality: ReadingQuality::Good,
+        };
+
+        // Encode to CBOR
+        let mut buf = alloc::vec![0u8; 0];
+        minicbor::encode(&reading, &mut buf).expect("encode failed");
+
+        // Verify it's compact enough for LoRa
+        // A single reading should be well under 30 bytes
+        assert!(buf.len() < 30, "reading CBOR too large: {} bytes", buf.len());
+
+        // Decode and verify roundtrip
+        let decoded: Reading = minicbor::decode(&buf).expect("decode failed");
+        assert_eq!(reading, decoded);
+    }
+
+    #[test]
+    fn cbor_roundtrip_payload() {
+        let payload = TransmissionPayload {
+            node_id: 1,
+            sequence: 42,
+            battery_mv: 3700,
+            readings: alloc::vec![
+                Reading {
+                    timestamp_ms: 1712345678000,
+                    channel: 0,
+                    raw_value: 1650,
+                    calibrated_value: 7023,
+                    unit: MeasurementUnit::Ph,
+                    quality: ReadingQuality::Good,
+                },
+                Reading {
+                    timestamp_ms: 1712345678000,
+                    channel: 1,
+                    raw_value: 890,
+                    calibrated_value: 1250,
+                    unit: MeasurementUnit::Ec,
+                    quality: ReadingQuality::Good,
+                },
+            ],
+        };
+
+        let mut buf = alloc::vec![0u8; 0];
+        minicbor::encode(&payload, &mut buf).expect("encode failed");
+
+        // Two-reading payload should fit comfortably in LoRa
+        assert!(buf.len() < 100, "payload CBOR too large: {} bytes", buf.len());
+
+        let decoded: TransmissionPayload = minicbor::decode(&buf).expect("decode failed");
+        assert_eq!(payload.node_id, decoded.node_id);
+        assert_eq!(payload.readings.len(), decoded.readings.len());
+    }
+
+    #[test]
+    fn channel_bitmask_logic() {
+        let config = SensorConfig {
+            sample_interval_secs: 30,
+            active_channels: 0b00000101, // channels 0 and 2 active
+            calibrations: alloc::vec![
+                Calibration::identity(),    // ch 0
+                Calibration::identity(),    // ch 1 (inactive but cal exists)
+            ],
+        };
+
+        assert!(config.is_channel_active(0));
+        assert!(!config.is_channel_active(1));
+        assert!(config.is_channel_active(2));
+        assert!(!config.is_channel_active(7));
+        assert!(!config.is_channel_active(8)); // out of range
+
+        // Channel 2 has no cal entry — should fall back to identity
+        let cal2 = config.cal_for(2);
+        assert_eq!(cal2.slope, 1000);
+        assert_eq!(cal2.offset, 0);
+    }
+}

crates/synapse-sensor/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "synapse-sensor"
+description = "WASM sensor module — runs on MCU (wasm3) and gateway (wasmtime)"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[lib]
+# cdylib produces a .wasm file when targeting wasm32
+# rlib allows other Rust crates to depend on this for testing
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+synapse-core = { path = "../synapse-core", default-features = false }
+minicbor = { workspace = true }
+heapless = { workspace = true }
+dlmalloc = { version = "0.2", features = ["global"] }
+
+# wit-bindgen generates guest-side bindings from the WIT definition
+# Only needed when building as a component (gateway/host targets)
+# For the MCU target (core wasm via wasm3), we use raw exports instead
+# wit-bindgen = { version = "0.36", optional = true }
+
+[features]
+default = []
+# Enable for component model builds (gateway/host)
+# Disable for core module builds (MCU via wasm3)
+# component = ["wit-bindgen"]

crates/synapse-sensor/src/lib.rs

@@ -0,0 +1,386 @@
+// Synapse Agriculture — Sensor WASM Module
+//
+// This is the "application" that runs inside the wasm3 runtime on the MCU.
+// The wasm3 runtime is the "kernel" flashed onto the RP2350.
+// This module is deployed separately via LoRa OTA from the gateway.
+//
+// Architecture:
+//   RP2350 boots → wasm3 runtime starts → loads this .wasm from flash
+//   → calls guest_init() → enters main loop calling guest_sample()
+//   → module calls host functions (read_i2c, transmit, sleep) via imports
+//
+// The host functions are implemented in C/Rust on the RP2350 bare metal
+// firmware. They talk to real hardware. This module never touches hardware
+// directly — it only sees the sandbox the host exposes.
+
+#![no_std]
+
+extern crate alloc;
+
+// Required for no_std WASM: global allocator and panic handler.
+// On the real MCU, you'd use a fixed-size bump allocator (e.g., embedded-alloc).
+// For now, dlmalloc works for WASM targets and is what wasm-pack uses.
+use alloc::vec::Vec;
+
+#[cfg(target_arch = "wasm32")]
+#[global_allocator]
+static ALLOC: dlmalloc::GlobalDlmalloc = dlmalloc::GlobalDlmalloc;
+
+#[cfg(target_arch = "wasm32")]
+#[panic_handler]
+fn panic(_info: &core::panic::PanicInfo) -> ! {
+    core::arch::wasm32::unreachable()
+}
+use synapse_core::{
+    Calibration, MeasurementUnit, Reading, ReadingQuality,
+    SensorConfig, TransmissionPayload,
+};
+
+// ---------------------------------------------------------------------------
+// Host function imports — these are provided by the wasm3 runtime
+// ---------------------------------------------------------------------------
+// For the MCU target, these are raw extern "C" imports that wasm3 links
+// at module load time. The RP2350 firmware registers these functions
+// with the wasm3 runtime before instantiating the module.
+//
+// For the component model target (gateway/host), these would come from
+// wit-bindgen instead. That's a future enhancement — for now, we target
+// core wasm only, which is what wasm3 supports.
+
+extern "C" {
+    /// Read bytes from an I2C device.
+    /// Returns number of bytes actually read, or negative on error.
+    /// Data is written to the `buf` pointer (must be in WASM linear memory).
+    fn host_read_i2c(address: u8, register: u8, buf: *mut u8, buf_len: u8) -> i32;
+
+    /// Read a raw 12-bit ADC value from the specified channel.
+    /// Returns the value (0-4095) or negative on error.
+    fn host_read_adc(channel: u8) -> i32;
+
+    /// Get current timestamp in milliseconds from RTC or host clock.
+    fn host_get_timestamp_ms() -> u64;
+
+    /// Transmit a LoRa packet. Data is read from the `buf` pointer.
+    /// Returns number of bytes queued, or negative on error.
+    fn host_transmit(buf: *const u8, buf_len: u32) -> i32;
+
+    /// Sleep for the specified number of milliseconds.
+    /// The WASM module yields execution; host enters low-power mode.
+    fn host_sleep_ms(duration_ms: u32);
+
+    /// Log a message (for debugging — may be compiled out on MCU).
+    fn host_log(level: u8, msg: *const u8, msg_len: u32);
+}
+
+// ---------------------------------------------------------------------------
+// Safe wrappers around host imports
+// ---------------------------------------------------------------------------
+
+fn read_i2c(address: u8, register: u8, buf: &mut [u8]) -> Result<usize, ReadingQuality> {
+    let result = unsafe { host_read_i2c(address, register, buf.as_mut_ptr(), buf.len() as u8) };
+    if result < 0 {
+        Err(ReadingQuality::Fault)
+    } else {
+        Ok(result as usize)
+    }
+}
+
+fn read_adc(channel: u8) -> Result<u16, ReadingQuality> {
+    let result = unsafe { host_read_adc(channel) };
+    if result < 0 {
+        Err(ReadingQuality::Fault)
+    } else {
+        Ok(result as u16)
+    }
+}
+
+fn timestamp_ms() -> u64 {
+    unsafe { host_get_timestamp_ms() }
+}
+
+fn transmit(data: &[u8]) -> Result<usize, ReadingQuality> {
+    let result = unsafe { host_transmit(data.as_ptr(), data.len() as u32) };
+    if result < 0 {
+        Err(ReadingQuality::Fault)
+    } else {
+        Ok(result as usize)
+    }
+}
+
+fn sleep(ms: u32) {
+    unsafe { host_sleep_ms(ms) }
+}
+
+fn log_info(msg: &str) {
+    unsafe { host_log(1, msg.as_ptr(), msg.len() as u32) }
+}
+
+// ---------------------------------------------------------------------------
+// Module state — lives in WASM linear memory, persists across calls
+// ---------------------------------------------------------------------------
+
+/// Global module state. Initialized in guest_init, used in guest_sample.
+/// This is safe because WASM is single-threaded — no concurrency concerns.
+static mut STATE: Option<ModuleState> = None;
+
+struct ModuleState {
+    config: SensorConfig,
+    sequence: u16,
+    node_id: u16,
+}
+
+// ---------------------------------------------------------------------------
+// Atlas Scientific EZO protocol helpers
+// ---------------------------------------------------------------------------
+// Atlas Scientific EZO-series probes (pH, EC, DO, ORP) use a simple
+// I2C protocol: write a command byte, wait, read the response.
+// Response format: [status_byte, ascii_data...]
+// Status: 1 = success, 2 = failed, 254 = pending, 255 = no data
+
+const ATLAS_CMD_READ: u8 = b'R';
+const ATLAS_STATUS_SUCCESS: u8 = 1;
+
+/// Read a value from an Atlas Scientific EZO probe.
+/// Returns the reading as fixed-point * 1000, or an error quality.
+fn read_atlas_ezo(i2c_address: u8) -> Result<i32, ReadingQuality> {
+    // Send read command
+    let cmd = [ATLAS_CMD_READ];
+    let result = unsafe {
+        host_read_i2c(i2c_address, cmd[0], core::ptr::null_mut(), 0)
+    };
+    if result < 0 {
+        return Err(ReadingQuality::Fault);
+    }
+
+    // Wait for measurement (Atlas EZO needs ~900ms for pH)
+    sleep(1000);
+
+    // Read response (up to 16 bytes: status + ASCII float)
+    let mut buf = [0u8; 16];
+    let bytes_read = read_i2c(i2c_address, 0, &mut buf)?;
+
+    if bytes_read < 2 || buf[0] != ATLAS_STATUS_SUCCESS {
+        return Err(ReadingQuality::Fault);
+    }
+
+    // Parse ASCII float response to fixed-point * 1000
+    // Atlas returns something like "7.23\0" as ASCII bytes
+    parse_ascii_fixed_point(&buf[1..bytes_read])
+        .ok_or(ReadingQuality::Degraded)
+}
+
+/// Parse ASCII decimal string (e.g., "7.23") to fixed-point * 1000 (7230).
+/// No floating point used — pure integer parsing for MCU efficiency.
+fn parse_ascii_fixed_point(bytes: &[u8]) -> Option<i32> {
+    let mut result: i32 = 0;
+    let mut decimal_places: i32 = -1; // -1 = haven't seen decimal point yet
+    let mut negative = false;
+
+    for &b in bytes {
+        match b {
+            b'-' if result == 0 => negative = true,
+            b'0'..=b'9' => {
+                result = result * 10 + (b - b'0') as i32;
+                if decimal_places >= 0 {
+                    decimal_places += 1;
+                }
+            }
+            b'.' => {
+                if decimal_places >= 0 {
+                    return None; // second decimal point
+                }
+                decimal_places = 0;
+            }
+            0 | b'\r' | b'\n' => break, // null terminator or newline
+            _ => return None,           // unexpected character
+        }
+    }
+
+    // Scale to * 1000 fixed-point
+    let scale = match decimal_places {
+        -1 | 0 => 1000, // no decimal or "7." → 7000
+        1 => 100,        // "7.2" → 7200
+        2 => 10,         // "7.23" → 7230
+        3 => 1,          // "7.230" → 7230
+        _ => return None, // more than 3 decimal places, truncate would lose data
+    };
+
+    result *= scale;
+    if negative {
+        result = -result;
+    }
+    Some(result)
+}
+
+// ---------------------------------------------------------------------------
+// Guest exports — called by the wasm3 host runtime
+// ---------------------------------------------------------------------------
+
+/// Called once at boot. Receives serialized config via CBOR.
+/// Returns 1 on success, 0 on failure.
+#[no_mangle]
+pub extern "C" fn guest_init(config_ptr: *const u8, config_len: u32, node_id: u16) -> u32 {
+    let config_bytes = unsafe {
+        core::slice::from_raw_parts(config_ptr, config_len as usize)
+    };
+
+    match minicbor::decode::<SensorConfig>(config_bytes) {
+        Ok(config) => {
+            log_info("sensor module initialized");
+            unsafe {
+                STATE = Some(ModuleState {
+                    config,
+                    sequence: 0,
+                    node_id,
+                });
+            }
+            1
+        }
+        Err(_) => {
+            log_info("failed to parse config");
+            0
+        }
+    }
+}
+
+/// Called each sample cycle. Reads all active sensors, builds payload,
+/// serializes to CBOR, and transmits via LoRa.
+/// Returns number of bytes transmitted, or 0 on failure.
+#[no_mangle]
+pub extern "C" fn guest_sample() -> u32 {
+    let state = unsafe {
+        match STATE.as_mut() {
+            Some(s) => s,
+            None => return 0,
+        }
+    };
+
+    let now = timestamp_ms();
+    let mut readings = Vec::new();
+
+    // Read each active channel
+    for ch in 0..8u8 {
+        if !state.config.is_channel_active(ch) {
+            continue;
+        }
+
+        let cal = state.config.cal_for(ch);
+
+        // For this reference implementation, channels 0-3 are Atlas EZO I2C
+        // with addresses 0x63 (pH), 0x64 (EC), 0x61 (DO), 0x62 (ORP).
+        // Channels 4-7 are ADC inputs for analog sensors.
+        // Real deployments would have this mapping in the config.
+        let (raw, unit, quality) = match ch {
+            0 => match read_atlas_ezo(0x63) {
+                Ok(v) => (v, MeasurementUnit::Ph, ReadingQuality::Good),
+                Err(q) => (0, MeasurementUnit::Ph, q),
+            },
+            1 => match read_atlas_ezo(0x64) {
+                Ok(v) => (v, MeasurementUnit::Ec, ReadingQuality::Good),
+                Err(q) => (0, MeasurementUnit::Ec, q),
+            },
+            2 => match read_atlas_ezo(0x61) {
+                Ok(v) => (v, MeasurementUnit::DissolvedOxygen, ReadingQuality::Good),
+                Err(q) => (0, MeasurementUnit::DissolvedOxygen, q),
+            },
+            3 => match read_atlas_ezo(0x62) {
+                Ok(v) => (v, MeasurementUnit::Orp, ReadingQuality::Good),
+                Err(q) => (0, MeasurementUnit::Orp, q),
+            },
+            4..=7 => match read_adc(ch - 4) {
+                Ok(v) => (v as i32, MeasurementUnit::MoistureVwc, ReadingQuality::Good),
+                Err(q) => (0, MeasurementUnit::MoistureVwc, q),
+            },
+            _ => continue,
+        };
+
+        readings.push(Reading {
+            timestamp_ms: now,
+            channel: ch,
+            raw_value: raw,
+            calibrated_value: cal.apply(raw),
+            unit,
+            quality,
+        });
+    }
+
+    // Build transmission payload
+    let payload = TransmissionPayload {
+        node_id: state.node_id,
+        sequence: state.sequence,
+        battery_mv: read_adc(7).unwrap_or(0), // ADC ch7 = battery voltage divider
+        readings,
+    };
+
+    // Increment sequence (wraps at u16::MAX)
+    state.sequence = state.sequence.wrapping_add(1);
+
+    // Serialize to CBOR and transmit
+    let mut buf = Vec::new();
+    match minicbor::encode(&payload, &mut buf) {
+        Ok(()) => {
+            match transmit(&buf) {
+                Ok(n) => n as u32,
+                Err(_) => {
+                    log_info("transmit failed");
+                    0
+                }
+            }
+        }
+        Err(_) => {
+            log_info("cbor encode failed");
+            0
+        }
+    }
+}
+
+/// Receive new config from gateway. Returns 1 on success, 0 on failure.
+#[no_mangle]
+pub extern "C" fn guest_reconfigure(config_ptr: *const u8, config_len: u32) -> u32 {
+    let config_bytes = unsafe {
+        core::slice::from_raw_parts(config_ptr, config_len as usize)
+    };
+
+    match minicbor::decode::<SensorConfig>(config_bytes) {
+        Ok(config) => {
+            if let Some(state) = unsafe { STATE.as_mut() } {
+                state.config = config;
+                log_info("reconfigured");
+                1
+            } else {
+                0
+            }
+        }
+        Err(_) => 0,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests — run natively on Houston, not under WASM
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_ascii_ph() {
+        assert_eq!(parse_ascii_fixed_point(b"7.23"), Some(7230));
+        assert_eq!(parse_ascii_fixed_point(b"4.0"), Some(4000));
+        assert_eq!(parse_ascii_fixed_point(b"14"), Some(14000));
+        assert_eq!(parse_ascii_fixed_point(b"0.5"), Some(500));
+        assert_eq!(parse_ascii_fixed_point(b"-1.5"), Some(-1500));
+    }
+
+    #[test]
+    fn parse_ascii_null_terminated() {
+        assert_eq!(parse_ascii_fixed_point(b"7.23\0\0\0"), Some(7230));
+        assert_eq!(parse_ascii_fixed_point(b"4.01\r\n"), Some(4010));
+    }
+
+    #[test]
+    fn parse_ascii_rejects_garbage() {
+        assert_eq!(parse_ascii_fixed_point(b"abc"), None);
+        assert_eq!(parse_ascii_fixed_point(b"7.2.3"), None);
+    }
+}

crates/synapse-web/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "synapse-web"
+description = "Build a Farm — browser WASM frontend"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+synapse-core = { path = "../synapse-core" }  # std features = default
+minicbor = { workspace = true }
+# Leptos for reactive WASM UI — uncomment when ready to build frontend
+# leptos = { version = "0.7", features = ["csr"] }
+# leptos_meta = { version = "0.7" }
+# leptos_router = { version = "0.7" }

crates/synapse-web/src/lib.rs

@@ -0,0 +1,101 @@
+// Synapse Agriculture — Build a Farm Web Frontend
+//
+// This crate compiles to WASM and runs in the browser.
+// It shares synapse-core types with the sensor modules,
+// meaning the same Reading/TransmissionPayload types that
+// the MCU produces are what the dashboard renders.
+//
+// For now this is a stub proving the shared type import works.
+// Leptos UI comes next once the core+sensor crates stabilize.
+
+use synapse_core::{
+    MeasurementUnit, Reading, ReadingQuality, TransmissionPayload,
+};
+
+/// Demonstrate that synapse-core types work in std/browser context.
+/// This will become the data layer for the Leptos dashboard.
+pub fn decode_payload(cbor_bytes: &[u8]) -> Result<TransmissionPayload, String> {
+    minicbor::decode(cbor_bytes).map_err(|e| format!("CBOR decode error: {e}"))
+}
+
+/// Format a reading for dashboard display.
+/// Uses the std-only helpers from synapse-core (calibrated_f64, unit_str).
+pub fn format_reading(reading: &Reading) -> String {
+    let quality_indicator = match reading.quality {
+        ReadingQuality::Good => "",
+        ReadingQuality::Degraded => " ⚠",
+        ReadingQuality::CalNeeded => " 🔧",
+        ReadingQuality::Fault => " ❌",
+    };
+
+    format!(
+        "{:.2} {}{}",
+        reading.calibrated_f64(),
+        reading.unit_str(),
+        quality_indicator
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use synapse_core::Calibration;
+
+    #[test]
+    fn format_ph_reading() {
+        let r = Reading {
+            timestamp_ms: 1712345678000,
+            channel: 0,
+            raw_value: 1650,
+            calibrated_value: 7230,
+            unit: MeasurementUnit::Ph,
+            quality: ReadingQuality::Good,
+        };
+        let s = format_reading(&r);
+        assert!(s.contains("7.23"), "expected '7.23' in '{s}'");
+        assert!(s.contains("pH"), "expected 'pH' in '{s}'");
+    }
+
+    #[test]
+    fn format_fault_reading() {
+        let r = Reading {
+            timestamp_ms: 0,
+            channel: 0,
+            raw_value: 0,
+            calibrated_value: 0,
+            unit: MeasurementUnit::DissolvedOxygen,
+            quality: ReadingQuality::Fault,
+        };
+        let s = format_reading(&r);
+        assert!(s.contains("❌"), "expected fault indicator in '{s}'");
+    }
+
+    #[test]
+    fn cbor_roundtrip_from_simulated_node() {
+        // Simulate what a sensor node would transmit
+        let payload = TransmissionPayload {
+            node_id: 1,
+            sequence: 0,
+            battery_mv: 3700,
+            readings: vec![Reading {
+                timestamp_ms: 1712345678000,
+                channel: 0,
+                raw_value: 1650,
+                calibrated_value: 7230,
+                unit: MeasurementUnit::Ph,
+                quality: ReadingQuality::Good,
+            }],
+        };
+
+        // Encode (as the MCU would)
+        let mut buf = Vec::new();
+        minicbor::encode(&payload, &mut buf).unwrap();
+
+        // Decode (as the browser would)
+        let decoded = decode_payload(&buf).unwrap();
+        assert_eq!(decoded.node_id, 1);
+
+        let formatted = format_reading(&decoded.readings[0]);
+        assert!(formatted.contains("7.23"));
+    }
+}

flake.nix

@@ -0,0 +1,96 @@
+{
+  description = "Synapse Agriculture — WASM-native farm stack development environment";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    rust-overlay.url = "github:oxalica/rust-overlay";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, nixpkgs, rust-overlay, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        overlays = [ (import rust-overlay) ];
+        pkgs = import nixpkgs { inherit system overlays; };
+
+        # Rust stable with WASM targets.
+        # Two targets, two purposes:
+        #   wasm32-unknown-unknown → bare WASM for MCU (wasm3) and browser
+        #   wasm32-wasip1          → WASI preview 1 for gateway/host (wasmtime)
+        rustToolchain = pkgs.rust-bin.stable.latest.default.override {
+          extensions = [ "rust-src" "rust-analyzer" ];
+          targets = [
+            "wasm32-unknown-unknown"
+            "wasm32-wasip1"
+          ];
+        };
+
+      in
+      {
+        devShells.default = pkgs.mkShell {
+          buildInputs = with pkgs; [
+            # ── Rust compilation ──────────────────────────────────────
+            rustToolchain
+
+            # ── WASM runtimes ─────────────────────────────────────────
+            wasmtime       # Full WASI + Component Model runtime
+                           # Tests gateway/host modules with all capabilities
+
+            # ── WASM binary tools ─────────────────────────────────────
+            binaryen       # wasm-opt: aggressive size optimization
+                           # wasm-opt -Oz -o small.wasm big.wasm
+                           # Critical for MCU — can cut binaries 40-60%
+
+            wabt           # wasm2wat / wat2wasm: bytecode inspection
+                           # When something breaks, read the WAT
+
+            wasm-tools     # Bytecode Alliance multi-tool:
+                           #   validate, component lower, strip, compose
+                           # component lower = component → core wasm for MCU
+
+            # ── Web frontend ──────────────────────────────────────────
+            trunk          # Dev server for Leptos/Yew WASM apps
+                           # Handles wasm-bindgen, assets, hot reload
+            wasm-pack      # WASM npm package builder (JS interop)
+            wasm-bindgen-cli
+
+            # ── Size profiling ────────────────────────────────────────
+            twiggy         # WASM code size profiler
+                           # twiggy top module.wasm — largest functions
+                           # twiggy dominators module.wasm — dep graph
+                           # RP2350 budget: ~400KB for module + heap
+
+            # ── Build deps ────────────────────────────────────────────
+            cmake          # For building wasm3 from source
+            pkg-config
+            openssl
+
+            # ── Dev workflow ──────────────────────────────────────────
+            cargo-watch    # cargo watch -x test — auto-test on save
+          ];
+
+          shellHook = ''
+            echo ""
+            echo "  ┌──────────────────────────────────────────────┐"
+            echo "  │  Synapse Agriculture — WASM Dev Environment  │"
+            echo "  └──────────────────────────────────────────────┘"
+            echo ""
+            echo "  Rust:      $(rustc --version 2>/dev/null || echo 'loading...')"
+            echo "  wasmtime:  $(wasmtime --version 2>/dev/null || echo 'loading...')"
+            echo "  wasm-opt:  $(wasm-opt --version 2>/dev/null || echo 'loading...')"
+            echo ""
+            echo "  Build targets:"
+            echo "    wasm32-unknown-unknown  → MCU (wasm3) + browser"
+            echo "    wasm32-wasip1           → gateway/host (wasmtime)"
+            echo ""
+            echo "  Quick start:"
+            echo "    cargo test                                      all native tests"
+            echo "    cargo build -p synapse-sensor --target wasm32-unknown-unknown --release"
+            echo "    wasm-opt -Oz -o opt.wasm target/.../synapse_sensor.wasm"
+            echo "    twiggy top opt.wasm                             size check"
+            echo ""
+          '';
+        };
+      }
+    );
+}

run.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+export PATH="/run/current-system/sw/bin:/root/.nix-profile/bin:/nix/var/nix/profiles/default/bin:$PATH"
+set -euo pipefail
+cd /opt/synapse-wasm
+
+echo "=== ENV ==="
+rustc --version
+cargo --version
+
+echo ""
+echo "=== STEP 1: NATIVE TESTS ==="
+cargo test --workspace 2>&1
+
+echo ""
+echo "=== STEP 2: WASM TARGET CHECK ==="
+if rustc --print target-list | grep -q wasm32-unknown-unknown; then
+    echo "wasm32 target available — building..."
+    cargo build --package synapse-sensor --target wasm32-unknown-unknown --release 2>&1
+    WASM="target/wasm32-unknown-unknown/release/synapse_sensor.wasm"
+    RAW=$(wc -c < "$WASM")
+    echo "Raw WASM: $RAW bytes ($((RAW/1024))KB)"
+    
+    # Try wasm-opt if available
+    if command -v wasm-opt &>/dev/null; then
+        mkdir -p target/wasm-opt
+        wasm-opt -Oz --strip-debug --strip-producers -o target/wasm-opt/synapse_sensor.wasm "$WASM"
+        OPT=$(wc -c < target/wasm-opt/synapse_sensor.wasm)
+        echo "Optimized: $OPT bytes ($((OPT/1024))KB) — $(( (RAW - OPT) * 100 / RAW ))% reduction"
+    fi
+    
+    if command -v twiggy &>/dev/null; then
+        echo ""
+        echo "=== TWIGGY TOP 10 ==="
+        twiggy top target/wasm-opt/synapse_sensor.wasm -n 10 2>&1 || true
+    fi
+
+    if command -v wasm-tools &>/dev/null; then
+        echo ""
+        echo "=== VALIDATE ==="
+        wasm-tools validate target/wasm-opt/synapse_sensor.wasm 2>&1 && echo "VALID" || echo "INVALID"
+    fi
+
+    if command -v wasm2wat &>/dev/null; then
+        echo ""
+        echo "=== EXPORTS ==="
+        wasm2wat "$WASM" 2>/dev/null | grep 'export' || echo "(none)"
+        echo ""
+        echo "=== IMPORTS ==="
+        wasm2wat "$WASM" 2>/dev/null | grep 'import' || echo "(none)"
+    fi
+else
+    echo "wasm32 target NOT in system rustc — need NixOS config update"
+fi
+
+echo ""
+echo "=== COMPLETE ==="

shell.nix

@@ -0,0 +1,11 @@
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.mkShell {
+  buildInputs = with pkgs; [
+    rustc cargo rustfmt clippy
+    gcc
+    pkg-config openssl
+    wasmtime binaryen wabt wasm-tools
+    twiggy trunk wasm-pack wasm-bindgen-cli cargo-watch
+  ];
+  shellHook = "export CC=gcc";
+}

wit/sensor.wit

@@ -0,0 +1,197 @@
+// Synapse Agriculture — Sensor Module Interface
+// This WIT definition is the IMMORTAL CONTRACT between:
+//   - Guest: sensor WASM modules (runs on MCU/gateway/host)
+//   - Host:  wasm3 (MCU), wasmtime (gateway/host), browser VM
+//
+// Adding a new sensor type = add to this file, regen bindings,
+// type-check catches every integration point at compile time.
+//
+// Changing this file is a BREAKING CHANGE across the entire stack.
+// Treat it like a database migration — versioned, reviewed, irreversible.
+
+package synapse:sensor@0.1.0;
+
+/// Types shared across all sensor modules and host runtimes.
+/// These compile into synapse-core and are used everywhere.
+interface types {
+    /// Sensor reading with metadata for provenance tracking
+    record reading {
+        /// Unix timestamp in milliseconds (from host clock or RTC)
+        timestamp-ms: u64,
+        /// Sensor channel identifier (maps to physical probe)
+        channel: u8,
+        /// Raw ADC or digital value before calibration
+        raw-value: s32,
+        /// Calibrated value as fixed-point (value * 1000)
+        /// Using s32 instead of f32 because wasm3 soft-float
+        /// on Cortex-M is slow and we don't need the precision
+        calibrated-value: s32,
+        /// Unit of measurement after calibration
+        unit: measurement-unit,
+        /// Quality/confidence flag from self-diagnostics
+        quality: reading-quality,
+    }
+
+    /// Fixed-point calibration coefficients for linear cal:
+    ///   calibrated = (raw * slope / 1000) + (offset / 1000)
+    /// Two-point cal: derive slope/offset from known standards
+    record calibration {
+        slope: s32,     // multiplied by 1000
+        offset: s32,    // multiplied by 1000
+    }
+
+    /// What physical quantity this reading represents
+    enum measurement-unit {
+        /// Water chemistry
+        ph,               // pH units (0-14)
+        ec,               // electrical conductivity, µS/cm
+        dissolved-oxygen,  // mg/L
+        orp,              // mV
+        temperature-water, // °C * 1000
+
+        /// Soil
+        moisture-vwc,     // volumetric water content, % * 1000
+        temperature-soil, // °C * 1000
+
+        /// Atmosphere
+        temperature-air,  // °C * 1000
+        humidity,         // % * 1000
+        pressure,         // hPa * 1000
+        light-lux,        // lux
+        light-par,        // µmol/m²/s (photosynthetically active)
+
+        /// Power (Layer 7)
+        voltage,          // mV
+        current,          // mA
+        power,            // mW
+        battery-soc,      // state of charge, % * 10
+    }
+
+    /// Self-diagnostic quality assessment
+    enum reading-quality {
+        good,
+        degraded,     // reading taken but outside expected range
+        cal-needed,   // calibration overdue or drift detected
+        fault,        // sensor not responding or shorted
+    }
+
+    /// Configuration pushed from gateway to node
+    record sensor-config {
+        /// Sampling interval in seconds
+        sample-interval-secs: u32,
+        /// Which channels to read (bitmask, up to 8 channels)
+        active-channels: u8,
+        /// Per-channel calibration (indexed by channel number)
+        calibrations: list<calibration>,
+    }
+
+    /// Compact transmission payload for LoRa
+    /// Designed to fit in a single LoRa packet (<= 242 bytes at SF7)
+    record transmission-payload {
+        /// Node identifier (unique per site)
+        node-id: u16,
+        /// Sequence number for dedup and gap detection
+        sequence: u16,
+        /// Battery voltage in mV (for power monitoring)
+        battery-mv: u16,
+        /// All readings from this sample cycle
+        readings: list<reading>,
+    }
+}
+
+/// Host functions provided TO the sensor module BY the runtime.
+/// The MCU firmware implements these against real hardware.
+/// The test harness implements them as mocks.
+/// The browser implements them as no-ops or simulations.
+interface host {
+    use types.{reading, calibration};
+
+    /// Read raw value from I2C sensor
+    /// address: 7-bit I2C device address (e.g., 0x63 for Atlas pH)
+    /// register: register to read from
+    /// length: bytes to read (max 32)
+    /// Returns: raw bytes from device, or error
+    read-i2c: func(address: u8, register: u8, length: u8) -> result<list<u8>, sensor-error>;
+
+    /// Read ADC channel (for analog sensors)
+    /// channel: ADC channel number (0-7 on RP2350)
+    /// Returns: raw 12-bit ADC value (0-4095)
+    read-adc: func(channel: u8) -> result<u16, sensor-error>;
+
+    /// Get current timestamp from RTC or host clock
+    get-timestamp-ms: func() -> u64;
+
+    /// Queue a LoRa transmission
+    /// payload: CBOR-encoded bytes to transmit
+    /// Returns: number of bytes queued, or error
+    transmit: func(payload: list<u8>) -> result<u32, sensor-error>;
+
+    /// Enter low-power sleep for specified duration
+    /// The WASM module yields execution here; host handles
+    /// actual MCU sleep modes (DORMANT on RP2350)
+    sleep-ms: func(duration-ms: u32);
+
+    /// Log a diagnostic message (forwarded to gateway if possible)
+    /// Compiled out / no-op on MCU builds via feature flag
+    log: func(level: log-level, message: string);
+
+    enum sensor-error {
+        /// Device not responding on bus
+        not-found,
+        /// Bus arbitration failure
+        bus-error,
+        /// Device returned NAK
+        nak,
+        /// Read timed out
+        timeout,
+        /// Transmission queue full
+        queue-full,
+        /// Generic / unclassified
+        other,
+    }
+
+    enum log-level {
+        debug,
+        info,
+        warn,
+        error,
+    }
+}
+
+/// The interface that every sensor module MUST implement.
+/// This is the guest-side contract — the "main" of the module.
+interface guest {
+    use types.{reading, sensor-config, transmission-payload};
+
+    /// Called once at boot. Host passes stored config.
+    /// Module initializes internal state, validates config.
+    /// Returns: true if init succeeded, false to signal fault.
+    init: func(config: sensor-config) -> bool;
+
+    /// Called each sample cycle by the host's main loop.
+    /// Module reads sensors (via host.read-i2c / host.read-adc),
+    /// applies calibration, builds readings list.
+    /// Returns: payload ready for LoRa transmission.
+    sample: func() -> transmission-payload;
+
+    /// Called when gateway pushes new config (e.g., new cal values).
+    /// Module validates and applies, returns success/failure.
+    reconfigure: func(config: sensor-config) -> bool;
+
+    /// Self-diagnostic. Module checks sensor responsiveness,
+    /// validates readings against expected ranges, reports health.
+    /// Returns: list of (channel, quality) pairs.
+    diagnose: func() -> list<tuple<u8, reading-quality>>;
+
+    use host.{sensor-error};
+
+    /// Redeclare quality enum access for diagnose return
+    use types.{reading-quality};
+}
+
+/// The complete world — wires guest to host.
+/// cargo-component uses this to generate the full bindings.
+world sensor-node {
+    import host;
+    export guest;
+}