# Strawberry distributed deployment (Salt) — contract for the deploying agent This directory holds the **Salt pillar** (data contract) for deploying Strawberry's distributed learning. The SLS **states** (install/config/egress/distribute) are to be authored separately (by the deploying agent) and consume this pillar. - `pillar/strawberry.sls` — the full pillar schema with defaults + required fields. - `pillar/top.sls` — example role assignment (sensor vs central). ## Architecture (what this release actually is) **Hub-and-spoke, NOT peer-to-peer.** ``` sensor nodes central node ------------ ------------ daemon -> store (also a sensor, optionally) strawberry export --out bundle.sbx --(Salt pull)--> bundle_dir/ strawberry fleet train bundle_dir --out shadow.sbm merge_rarity_overlay(...) -> fleet-overlay.sbo [NO CLI YET] model_dir/ <--(Salt push)---------- distribute: shadow.sbm + fleet-overlay.sbo (round 2+ exports carry fleet_bits) ``` - There is **no node-to-node transport**, no gossip/DHT, no decentralized aggregation. - Egress is **central-pull** (Salt orchestration / `cp.push` of a sealed, redacted bundle). The bundle artifact contract is stable, so an object store / mTLS collector can replace the pull later without daemon changes. - **Promotion is operator-only, never automatic.** States distribute `shadow.sbm`; a model only acts after `strawberry model promote` passes the pre-registered gate (`docs/evaluation/stage4-promotion-gate.md`). Keep promotion a human step. ## CLI surface the states invoke (exists today on `main`) - `strawberry export --out ` — sensor egress. Auto-includes fleet rarity when `/fleet-overlay.sbo` is present. - `strawberry fleet train --out ` — central merge + train shadow model. ## GAPS the deploying agent must close (honest status) 1. **No `strawberry fleet overlay` CLI.** `merge_rarity_overlay()` (sum per-node rarity sketches -> `fleet-overlay.sbo`) is a **library function only** — there is no CLI verb to produce the overlay on the central node. The overlay step in the pillar (`central.overlay_out`) cannot run until that verb is added (a small increment: `strawberry fleet overlay --out fleet-overlay.sbo`). 2. **`node_id` is not yet a daemon config key.** Export stamps `node_uid` from `read_node_uid("")` (machine-id/hostname hash). Wiring `config.node_id` through to export is a follow-up; until then, `config.node_id` in the pillar is advisory. 3. **No `--since` incremental export** — each export is a full pass over the store. 4. **No multi-node validation.** The pipeline is unit/component + single-binary tested; it has **not** been run as a real multi-node fleet (N daemons -> central pull -> merge across hosts -> distribute -> re-export). A docker-swarm end-to-end is the recommended acceptance test before fleet rollout (the plan's deferred `docker-live` milestone). ## Paths (binary defaults) - store / `db_path`: `/var/lib/strawberry/evidence` - `model_dir`: `/var/lib/strawberry/model` (holds `shadow.sbm`, `promoted.sbm`, `rarity.state`, `fleet-overlay.sbo`) ## Security invariants the states must preserve - `capture_redact_cmdline: true` (argv redaction before storage) — do not disable on a fleet. - No new inbound listener on sensor nodes — export is an outbound read-only artifact pulled over the trusted channel; the daemon sandbox stays intact. - Reviewed, sha256-pinned binaries only; verify the pin before install.