ae20809 · f8a7543 · f81d58f · c66c490 · d2bae2e · ff152bf
@@ -265,3 +265,34 @@
Not drawn yet, because nothing records it: latency per hop (page → relay → P
## Faster limits
A person runs this at the arm while nobody drives: `bun bench/limits-search.ts http://<arm>:8101` (add `--joint 2` for one joint; with no URL it runs on the fake bus). From today's 90 °/s and 360 °/s² it steps each joint's speed and acceleration up within the safety ranges (the gripper is skipped), sweeps at each step, and keeps the last step that did not make p95 error or overshoot worse, writing them through `PUT /settings`. It prints its command line, then a table of limits and p95 error, overshoot and time to arrive, before → after. It refuses to start while anyone drives or a STOP or E-stop is in force, and if one appears mid-run it stops and puts the starting limits back.
## Sensors & dosing (parts list, and the controller)
`src/doser.ts` is the dose controller: three loops (nutrient A, nutrient B, pH down), each `off`, `suggest` (default) or `auto`, with per-dose and per-day ml limits, a ≥10 min mixing wait, no dose on a stale (>30 min), uncalibrated or already-used reading, and a halt until the owner resumes when a reading is out of physical bounds or a dose did not move it. Every dose goes in the log book with its cause (rule, crew, owner). `topOff` runs the fresh-water pump until the high float or a time cap. Sensor and pump drivers are separate pulls and plug in as `Reading` sources and `Pump`s.
**Using it today.** The app builds the controller at boot over the Pi's real pumps (below); readings are the newest measurements in the log book. State (the day's doses, the stop, each loop's mode) is kept in `dosing.json` under `FORGE_APP_DATA` and survives a restart.
- **Page:** the owner sees a Dosing card on `/care`: each loop, its mode, what it would add, a **Do it** button, a mode picker, and a red "Dosing stopped" banner with **Resume dosing**. Guests and non-owners see nothing.
- **Terminal:** `/care dosing`, `/care dose <nutrientA|nutrientB|phDown> [ml]`, `/care mode <loop> <off|suggest|auto>`, `/care resume`. The server decides who may; all four are the owner's.
- **Crew (MCP):** `POST /care/mcp` speaks JSON-RPC (`initialize`, `tools/list`, `tools/call`) with the tools `readings`, `log`, `suggest_dose` and `dose`. A crew dose is refused unless the owner put that loop in `auto`, and is bound by the same limits. The crew cannot change a mode or resume.
  **Who may call:** every call needs a verified identity (the forge-signed header), or it gets 401, `tools/list` included. `readings` and `log` are for anyone signed in; `suggest_dose`, `dose` and `pumps` are the owner's (403 otherwise), like the card on `/care`. A crew agent calls with the owner's identity, and its dose is still the crew's: refused unless the loop is in `auto`. At most 60 calls a minute per identity (429).
- **Owner-only:** `setMode` and `resume` take the caller's cause and throw for anything but the owner. Modes are never raised by a rule or an agent.
**The pumps (`src/dose-pumps.ts` on the Pi, `src/arm-pumps.ts` in the relay).** The arm server runs the four pumps (nutrient A, nutrient B, pH down, top-off), like the grow light: each pump's switch is a GPIO line to a relay or MOSFET channel, or a Shelly plug (the light's drivers, `src/light-switch.ts`; a USB port can't carry a 12 V pump, so uhubctl isn't offered). Each pump turns ml into seconds with its own measured ml/s. Settings and the day's runs are kept in `dose-pumps.json` beside the arm's other data.
- **Set up, on `/care` → Dosing → Pumps (owner only):** *Wire* a pump (GPIO line, tick "closes on 0" for an active-low board, or a plug address). Tap **Run 10 s into a measuring cup** (also primes the tube), type the ml the cup caught, and **Save calibration**: 12 ml in 10 s is 1.2 ml/s. A new switch clears the calibration. For top-off, set the high float's GPIO line and the time cap (5–600 s, 120 by default), then **Top off now**: it runs until the float says full or the cap passes, and the log book gets *topoff*, or a note to check the jug when the cap stopped it.
- **Terminal:** `/care pumps`, `/care wire <pump> gpio <line> [low]` · `shelly <host>` · `none`, `/care prime <pump> [seconds]`, `/care calibrate <pump> <ml>`, `/care float <line|none> [low] [cap seconds]`, `/care topoff`. A pump is `nutrientA`, `nutrientB`, `phDown` or `topOff`.
- **Crew (MCP):** the `pumps` tool reads each pump's switch, ml/s, calibration date, today's ml and the float. The crew can't wire, prime, calibrate or top off.
- **Refused, not failed:** a pump with no switch or no calibration, or a dose past the Pi's own backstop (60 s in one run, 100 ml a pump a day, whatever the controller asks) answers 409 before anything switches. The controller then refuses that dose without counting it or stopping automation. A switch that fails once it was asked to close is a failure: the pump is switched off anyway (three tries), and dosing stops until the owner resumes.
- **Off, always:** every wired pump is switched off when the arm server starts, and after every run, including one that throws.
- **Only the relay asks the Pi:** the relay answers `/grow/dosing` from a browser with 404, owner or not, so no dose skips the controller's limits. The Pi's `GET`/`POST /grow/dosing` aren't gated on the arm server itself, like `/grow/light`: whoever reaches the arm server's port reaches them, and the backstop above is what holds there.
| Part | Module | Wiring | Price |
|---|---|---|---|
| Water temperature | DS18B20 waterproof, 4.7 kΩ pull-up | 1-Wire on GPIO4 | ~$4 |
| Air temp/humidity | SHT31 or BME280 breakout | I²C SDA/SCL (GPIO2/3), 3.3 V | ~$8 |
| ADC for probes | ADS1115 | I²C 0x48 | ~$7 |
| pH probe + board | analog pH kit (BNC) | ADS1115 A0 | ~$30 |
| EC probe + board | analog EC K=1 kit | ADS1115 A1 | ~$40 |
| Reservoir level | float switch (low), second float (high, for top-off) | GPIO17, GPIO27 to GND | ~$3 each |
| Dosing pumps ×3 | 12 V peristaltic, with a 4-channel MOSFET/relay board | GPIO22/23/24 → board, 12 V supply | ~$12 each + ~$6 |
| Top-off pump | 12 V diaphragm or peristaltic, jug of fresh water | GPIO25 → fourth channel | ~$10 |
| 12 V supply | 12 V 2 A | to the board, not the Pi | ~$10 |
@@ -80,6 +80,6 @@
const facts = new Facts({ file: join(dir, "facts.sqlite") });
const piSync = piSyncFromEnv(process.env, remote?.http ?? null, remote?.host ?? null, () => lobby.turns.snapshot().driver === null, dir);
const grow = { stills: new GrowStills(join(dir, "grow-stills"), { capBytes: Number(process.env.GROW_STILLS_CAP_MB) * 1e6 || undefined }), log: new GrowLog(join(dir, "grow-log.json")), everyMs: parseEvery(process.env.GROW_STILL_MINUTES) };
const careProfile = loadProfiles(BUILT_IN_DIR, join(dir, "care-profiles")).find((p) => p.id === (process.env.CARE_PROFILE ?? "spinach"));
const relay = await startRelay({ probeEveryMs: 300_000, sensorsMs: 600_000, care: careProfile ? { log: new CareLog(join(dir, "care.json")), profile: careProfile } : undefined, grow, stations: new StationHub(join(dir, "stations.json")), facts, piSync: piSync ?? undefined, host, port, simulation: `http://127.0.0.1:${simulation.port}`, remote, problem, lobby, cameras, leaders, video, summaryEveryMs: 60_000, holdFile: join(dir, "hold.json"), baselineFile: join(dir, "servo-factory.json") });
const relay = await startRelay({ probeEveryMs: 300_000, sensorsMs: 600_000, care: careProfile ? { log: new CareLog(join(dir, "care.json")), profile: careProfile, dosingFile: join(dir, "dosing.json") } : undefined, grow, stations: new StationHub(join(dir, "stations.json")), facts, piSync: piSync ?? undefined, host, port, simulation: `http://127.0.0.1:${simulation.port}`, remote, problem, lobby, cameras, leaders, video, summaryEveryMs: 60_000, holdFile: join(dir, "hold.json"), baselineFile: join(dir, "servo-factory.json") });
const { mode, host: armHost } = relay.link();
console.log(`arm on http://${host}:${relay.port}  (${mode === "simulated" ? "simulated" : `arm ${armHost}: ${mode}`}; data in ${dir}${local ? "; local: every visitor drives as the owner" : ""})`);
@@ -0,0 +1,136 @@
/**
 * The relay's side of the dosing pumps, which live on the arm server (src/dose-pumps.ts on the Pi):
 *   armPumps     the controller's Pump for each loop: a dose is POST /grow/dosing {"action": "dose"}; a 409 (nothing ran)
 *                becomes PumpRefused, anything else a failure that halts automation
 *   readDosing   GET /grow/dosing read field by field, so a wrong answer shows as less, never as markup or a crash
 *   pumpRequest  the owner's setup forms (wire, float, prime, calibrate, top off) as the Pi's JSON; never a dose, which
 *                goes through the controller's limits alone
 */
import { LOOPS, PumpRefused, type LoopId, type Pump } from "./doser.ts";
import { PUMP_IDS, type DosingView, type FloatConfig, type PumpId, type PumpView } from "./dose-pumps.ts";
export type PumpAnswer = { ok: true; body: unknown } | { ok: false; status: number; error: string };
/** How the relay reaches the Pi's pumps; `status` 0 is no answer. */
export interface PumpHooks {
  read(): Promise<DosingView | null>;
  write(body: Record<string, unknown>, timeoutMs: number): Promise<PumpAnswer>;
}
/** Room for the Pi's longest dose (60 s) and its longest top-off (600 s), and the trip. */
export const DOSE_TIMEOUT_MS = 75_000;
export const FILL_TIMEOUT_MS = 620_000;
export const PUMP_LABEL: Record<PumpId, string> = { nutrientA: "Nutrient A", nutrientB: "Nutrient B", phDown: "pH down", topOff: "Top-off" };
export function armPumps(hooks: PumpHooks): Record<LoopId, Pump> {
  const pump = (id: LoopId): Pump => ({
    async dose(ml) {
      const a = await hooks.write({ action: "dose", pump: id, ml }, DOSE_TIMEOUT_MS);
      if (a.ok) return;
      if (a.status === 409) throw new PumpRefused(a.error);
      throw new Error(a.error);
    },
  });
  return Object.fromEntries(LOOPS.map((l) => [l, pump(l)])) as Record<LoopId, Pump>;
}
const obj = (v: unknown): Record<string, unknown> => (typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
const text = (v: unknown, max: number): string => (typeof v === "string" ? v.replace(/[\p{Cc}\p{Cf}]/gu, "").slice(0, max) : "");
const num = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
const pumpId = (v: unknown): PumpId | null => (PUMP_IDS.includes(v as PumpId) ? (v as PumpId) : null);
export function readDosing(body: unknown): DosingView | null {
  const b = obj(body);
  if (!Array.isArray(b.pumps)) return null;
  const pumps: PumpView[] = b.pumps.flatMap((x: unknown) => {
    const p = obj(x);
    const id = pumpId(p.id);
    const driver = text(p.driver, 20);
    return id ? [{ id, driver: driver === "gpio" || driver === "shelly" ? driver : null, mlPerSec: num(p.mlPerSec), calibratedAt: num(p.calibratedAt), dosedTodayMl: num(p.dosedTodayMl) ?? 0 }] : [];
  });
  const f = obj(b.float);
  const float: FloatConfig | null = typeof f.chip === "string" && /^gpiochip\d{1,2}$/.test(f.chip) && Number.isInteger(f.line) ? { chip: f.chip, line: f.line as number, activeLow: f.activeLow === true } : null;
  const pr = obj(b.primed);
  const primedPump = pumpId(pr.pump);
  return {
    pumps,
    float,
    full: typeof b.full === "boolean" ? b.full : null,
    capSec: num(b.capSec) ?? 0,
    primed: primedPump && num(pr.ms) !== null && num(pr.at) !== null ? { pump: primedPump, ms: pr.ms as number, at: pr.at as number } : null,
    running: pumpId(b.running),
    maxRunMs: num(b.maxRunMs) ?? 0,
    maxDayMl: num(b.maxDayMl) ?? 0,
    error: text(b.error, 300) || null,
  };
}
/** The setup actions the owner may ask of the Pi. `dose` is not one: a dose goes through the controller. */
export const SETUP_ACTIONS = ["switch", "float", "prime", "calibrate", "fill"] as const;
/**
 * The Pi's JSON for one of the card's forms (strings) or the terminal's JSON (typed); null when it is not a setup
 * action. Only shape is decided here: the Pi checks every value.
 */
export function pumpRequest(input: Record<string, unknown>): Record<string, unknown> | null {
  const get = (k: string) => (typeof input[k] === "string" ? (input[k] as string).trim() : input[k]);
  const n = (k: string) => {
    const v = get(k);
    return typeof v === "number" ? v : typeof v === "string" && /^\d{1,6}(\.\d{1,3})?$/.test(v) ? Number(v) : v;
  };
  const pump = get("pump");
  switch (get("action")) {
    case "switch": {
      if (input.switch !== undefined) return { action: "switch", pump, switch: input.switch };
      switch (get("driver")) {
        case "none":
          return { action: "switch", pump, switch: null };
        case "gpio":
          return { action: "switch", pump, switch: { driver: "gpio", chip: get("chip") || "gpiochip0", line: n("line"), activeLow: input.activeLow === "on" || input.activeLow === true } };
        case "shelly":
          return { action: "switch", pump, switch: { driver: "shelly", host: get("host"), gen: String(get("gen")) === "1" ? 1 : 2 } };
        default:
          return { action: "switch", pump, switch: { driver: get("driver") } };
      }
    }
    case "float": {
      const out: Record<string, unknown> = { action: "float" };
      if (get("line") === "" || get("line") === "none") out.float = null;
      else if (get("line") !== undefined) out.float = { chip: get("chip") || "gpiochip0", line: n("line"), activeLow: input.activeLow === "on" || input.activeLow === true };
      if (get("capSec") !== undefined && get("capSec") !== "") out.capSec = n("capSec");
      return out;
    }
    case "prime": {
      const sec = n("sec");
      return { action: "prime", pump, ms: typeof sec === "number" ? Math.round(sec * 1000) : sec };
    }
    case "calibrate":
      return { action: "calibrate", pump, ml: n("ml") };
    case "fill":
      return { action: "fill" };
    default:
      return null;
  }
}
/**
 * The Pi's pumps as the page reads them: the last answer at once when it is under `freshMs` old, a fresh read otherwise
 * (one in flight at a time). The very first read waits at most `firstWaitMs`, so a Pi that is down never holds /care up.
 */
export function cachedRead(read: () => Promise<DosingView | null>, freshMs = 5000, now: () => number = Date.now, firstWaitMs = 300) {
  let last: { at: number; view: DosingView | null } | null = null;
  let inflight: Promise<DosingView | null> | null = null;
  const refresh = (): Promise<DosingView | null> =>
    (inflight ??= read()
      .then((view) => ((last = { at: now(), view }), view))
      .finally(() => (inflight = null)));
  return {
    read: async (): Promise<DosingView | null> => {
      if (last && now() - last.at < freshMs) return last.view;
      if (last) return void refresh().catch(() => {}), last.view;
      return Promise.race([refresh(), new Promise<null>((r) => setTimeout(() => r(null), firstWaitMs))]);
    },
    refresh,
  };
}
@@ -0,0 +1,216 @@
import { expect, test } from "bun:test";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { createServer } from "node:http";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { CareLog } from "./care-log.ts";
import { fakeDoser, handleDosing, MCP_PER_MINUTE, rateLimit } from "./care-dosing.ts";
import { renderCare } from "./care-page.ts";
import { careCommand, dosingLines } from "./care-terminal.ts";
import { BUILT_IN_DIR, loadProfiles } from "./care-profile.ts";
import { Doser, LOOPS, topOff } from "./doser.ts";
const spinach = loadProfiles(BUILT_IN_DIR).find((p) => p.id === "spinach")!;
async function serve(who: "owner" | "guest" | "member", opts: { doser?: Doser; log?: CareLog; origin?: boolean } = {}) {
  const log = opts.log ?? new CareLog();
  const doser = opts.doser ?? fakeDoser(log);
  const server = createServer((req, res) => {
    const readBody = (r: typeof req, limit = 1 << 20) => new Promise<Buffer>((ok, no) => { const c: Buffer[] = []; let n = 0; r.on("data", (d: Buffer) => { n += d.length; if (n > limit) { no(new Error("body too large")); return; } c.push(d); }); r.on("end", () => ok(Buffer.concat(c))); });
    handleDosing(req, res, new URL(req.url!, "http://x").pathname, { doser, log, readBody, sameOrigin: () => opts.origin !== false, who: () => ({ owner: who === "owner", known: who !== "guest" }) }).then((hit) => hit || (res.writeHead(404), res.end()));
  });
  await new Promise<void>((ok) => server.listen(0, "127.0.0.1", ok));
  const base = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
  const post = (path: string, body: unknown) => fetch(base + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
  return { base, log, doser, post, close: () => server.close() };
}
test("the owner sees dosing, sets a mode, taps Do it, and resumes; the log book says it was simulated", async () => {
  const s = await serve("owner");
  try {
    s.log.add({ type: "measurement", kind: "ph", value: 7.2 });
    const state = (await (await fetch(`${s.base}/care/dosing`)).json()) as { simulated: boolean; loops: { id: string; mode: string; suggestion: { ml: number } | null }[] };
    expect(state.simulated).toBe(true);
    const ph = state.loops.find((l) => l.id === "phDown")!;
    expect(ph.mode).toBe("suggest");
    expect(ph.suggestion!.ml).toBeGreaterThan(0);
    const did = await s.post("/care/dosing/dose", { loop: "phDown" });
    expect(did.status).toBe(200);
    expect(s.log.entries().at(-1)).toMatchObject({ type: "observation" });
    expect((await s.post("/care/dosing/mode", { loop: "phDown", mode: "auto" })).status).toBe(200);
    expect(s.doser.loops.phDown.mode).toBe("auto");
    expect((await s.post("/care/dosing/mode", { loop: "phDown", mode: "wild" })).status).toBe(400);
    const second = await s.post("/care/dosing/dose", { loop: "phDown" });
    expect(second.status).toBe(409);
    expect((await s.post("/care/dosing/resume", {})).status).toBe(200);
    const form = await fetch(`${s.base}/care/dosing/mode`, { method: "POST", redirect: "manual", headers: { "content-type": "application/x-www-form-urlencoded" }, body: "loop=phDown&mode=off" });
    expect(form.status).toBe(303);
    expect(s.doser.loops.phDown.mode).toBe("off");
  } finally {
    s.close();
  }
});
test("a guest or a signed-in non-owner sees nothing and cannot dose, resume or set a mode", async () => {
  for (const who of ["guest", "member"] as const) {
    const s = await serve(who);
    try {
      expect((await fetch(`${s.base}/care/dosing`)).status).toBe(who === "guest" ? 401 : 403);
      for (const [path, body] of [["/care/dosing/dose", { loop: "phDown" }], ["/care/dosing/resume", {}], ["/care/dosing/mode", { loop: "phDown", mode: "auto" }]] as const) {
        expect((await s.post(path, body)).status).toBe(who === "guest" ? 401 : 403);
      }
      expect(s.doser.loops.phDown.mode).toBe("suggest");
    } finally {
      s.close();
    }
  }
});
test("a write from another origin is refused, and a body over the cap is cut off", async () => {
  const other = await serve("owner", { origin: false });
  try {
    expect((await other.post("/care/dosing/mode", { loop: "phDown", mode: "auto" })).status).toBe(403);
    expect(other.doser.loops.phDown.mode).toBe("suggest");
  } finally {
    other.close();
  }
  const s = await serve("owner");
  try {
    const big = await fetch(`${s.base}/care/dosing/mode`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ loop: "phDown", mode: "auto", pad: "x".repeat(10_000) }) });
    expect(big.status).toBe(413);
  } finally {
    s.close();
  }
});
test("crew tools over MCP, with the owner's verified identity: read and suggest, dose only in auto, never resume or set a mode", async () => {
  const s = await serve("owner");
  const call = async (name: string, args: object = {}) => ((await (await s.post("/care/mcp", { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } })).json()) as { result?: { isError: boolean; content: { text: string }[] }; error?: unknown });
  try {
    s.log.add({ type: "measurement", kind: "ph", value: 7.2 });
    const list = (await (await s.post("/care/mcp", { jsonrpc: "2.0", id: 1, method: "tools/list" })).json()) as { result: { tools: { name: string }[] } };
    expect(list.result.tools.map((t) => t.name)).toEqual(["readings", "log", "suggest_dose", "dose", "pumps"]);
    expect(JSON.parse((await call("readings")).result!.content[0]!.text).ph.value).toBe(7.2);
    expect(JSON.parse((await call("suggest_dose", { loop: "phDown" })).result!.content[0]!.text).ml).toBeGreaterThan(0);
    const refused = await call("dose", { loop: "phDown" });
    expect(refused.result!.isError).toBe(true);
    expect(refused.result!.content[0]!.text).toContain("only suggests");
    expect(s.log.entries().filter((e) => e.type !== "measurement")).toHaveLength(0);
    expect((await call("resume")).error).toBeDefined();
    expect((await call("setMode", { loop: "phDown", mode: "auto" })).error).toBeDefined();
    s.doser.setMode("phDown", "auto", "owner");
    const done = await call("dose", { loop: "phDown", ml: 2 });
    expect(done.result!.isError).toBe(false);
    const over = await call("dose", { loop: "phDown", ml: 500 });
    expect(over.result!.isError).toBe(true);
  } finally {
    s.close();
  }
});
test("MCP without a verified identity is refused 401 on every tool, dose in auto included; a signed-in non-owner gets the log book, never dosing", async () => {
  const guest = await serve("guest");
  const rpc = (srv: typeof guest, name: string, args: object = {}) => srv.post("/care/mcp", { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } });
  try {
    guest.log.add({ type: "measurement", kind: "ph", value: 7.2 });
    guest.doser.setMode("phDown", "auto", "owner");
    for (const [name, args] of [["readings", {}], ["log", {}], ["pumps", {}], ["suggest_dose", { loop: "phDown" }], ["dose", { loop: "phDown", ml: 2 }]] as const) {
      const r = await rpc(guest, name, args);
      expect(r.status).toBe(401);
    }
    expect((await guest.post("/care/mcp", { jsonrpc: "2.0", id: 1, method: "tools/list" })).status).toBe(401);
    expect(guest.doser.dosedToday("phDown")).toBe(0);
    expect(guest.log.entries().filter((e) => e.type !== "measurement")).toHaveLength(0);
  } finally {
    guest.close();
  }
  const member = await serve("member");
  try {
    member.doser.setMode("phDown", "auto", "owner");
    expect((await rpc(member, "log")).status).toBe(200);
    for (const [name, args] of [["pumps", {}], ["suggest_dose", { loop: "phDown" }], ["dose", { loop: "phDown", ml: 2 }]] as const) expect((await rpc(member, name, args)).status).toBe(403);
    expect(member.doser.dosedToday("phDown")).toBe(0);
  } finally {
    member.close();
  }
});
test("MCP is limited to 60 calls a minute per identity", () => {
  const l = rateLimit(MCP_PER_MINUTE);
  for (let i = 0; i < MCP_PER_MINUTE; i++) expect(l.take("a", 0)).toBe(true);
  expect(l.take("a", 1000)).toBe(false);
  expect(l.take("b", 1000)).toBe(true);
  expect(l.take("a", 60_000)).toBe(true);
});
test("the care page shows the card to the owner only, with Do it and a halted banner with Resume", async () => {
  const log = new CareLog();
  log.add({ type: "measurement", kind: "ph", value: 7.2 });
  const doser = fakeDoser(log);
  const view = { profile: spinach, log, now: Date.now(), signedIn: null };
  const html = renderCare({ ...view, owner: true, dosing: doser.status() });
  expect(html).toContain("data-dosing");
  expect(html).toContain("Do it");
  expect(html).not.toContain("data-halted");
  expect(renderCare({ ...view, owner: false })).not.toContain("data-dosing");
  doser.loops.phDown.mode = "auto";
  await doser.dose("phDown", "rule");
  const later = new Doser({ pumps: { nutrientA: { dose: async () => {} }, nutrientB: { dose: async () => {} }, phDown: { dose: async () => { throw new Error("jammed"); } } }, latest: () => undefined, calibrated: () => true, log, loops: { phDown: { mode: "auto" } } });
  later["s"].halted = "x <b>";
  const stopped = renderCare({ ...view, owner: true, dosing: later.status() });
  expect(stopped).toContain("data-halted");
  expect(stopped).toContain("Resume dosing");
  expect(stopped).toContain("x &lt;b&gt;");
});
test("the terminal words dosing as the same requests the page makes", () => {
  expect(careCommand(["dosing"], "")).toEqual({ method: "GET", path: "/care/dosing" });
  expect(careCommand(["dose", "phDown", "2"], "phDown 2")).toEqual({ method: "POST", path: "/care/dosing/dose", body: { loop: "phDown", ml: 2 }, timeoutMs: 80_000 });
  expect(careCommand(["mode", "phDown", "auto"], "")).toEqual({ method: "POST", path: "/care/dosing/mode", body: { loop: "phDown", mode: "auto" } });
  expect(careCommand(["resume"], "")).toEqual({ method: "POST", path: "/care/dosing/resume", body: {} });
  expect(careCommand(["dose", "water"], "")).toHaveProperty("print");
  expect(dosingLines({ halted: "bad", loops: [{ label: "pH down", mode: "suggest", reason: "no ph reading", dosedTodayMl: 0, maxDayMl: 15 }] })[0]).toContain("STOPPED");
});
test("controller fixes: only the owner changes modes or resumes, modes persist, a bad file halts, a pump failure halts, a read changes nothing, top-off turns off when on() throws", async () => {
  const dir = mkdtempSync(join(tmpdir(), "dose-"));
  try {
    const file = join(dir, "dosing.json");
    const log = new CareLog();
    log.add({ type: "measurement", kind: "ph", value: 7.2 });
    const a = fakeDoser(log, file);
    expect(() => a.setMode("phDown", "auto", "crew")).toThrow(/owner/);
    expect(() => a.resume("rule")).toThrow(/owner/);
    a.setMode("phDown", "auto", "owner");
    expect(fakeDoser(log, file).loops.phDown.mode).toBe("auto");
      
        junipercrew
        16d ago
        
      
      later["s"] and jam["d"] reach into private fields, so the test breaks on a rename that changes no behaviour. Expose a small test seam, or build the halted state through a real failing dose.
    
    writeFileSync(file, JSON.stringify({ halted: null, lastDoseAt: 0, usedReading: {}, pending: null, doses: null, modes: {} }));
    expect(fakeDoser(log, file).halted).toContain("unreadable");
    const t = Date.now();
    const jam = new Doser({ pumps: { nutrientA: { dose: async () => {} }, nutrientB: { dose: async () => {} }, phDown: { dose: async () => { throw new Error("jammed"); } } }, latest: () => ({ kind: "ph", value: 7.2, at: t, source: "sensor" }), calibrated: () => true, log, loops: { phDown: { mode: "auto" } }, now: () => t });
    const out = await jam.dose("phDown", "rule", 2);
    expect(out).toMatchObject({ ok: false, reason: expect.stringContaining("jammed") });
    expect(jam.halted).toContain("jammed");
    expect(jam.dosedToday("phDown")).toBe(2);
    expect(log.entries().at(-1)).toMatchObject({ type: "observation", text: expect.stringContaining("jammed") });
    // a read does not halt: an out-of-bounds reading is reported by suggest, and only a dose stops automation
    const wild = new Doser({ pumps: jam["d"].pumps, latest: () => ({ kind: "ph", value: 99, at: t, source: "sensor" }), calibrated: () => true, log, now: () => t });
    expect(wild.suggest("phDown")).toHaveProperty("reason");
    expect(wild.halted).toBeNull();
    wild.loops.phDown.mode = "auto";
    await wild.dose("phDown", "rule", 1);
    expect(wild.halted).toContain("outside");
    const calls: string[] = [];
    await expect(topOff({ on: async () => { calls.push("on"); throw new Error("relay"); }, off: async () => void calls.push("off") }, async () => false, { capMs: 1000 })).rejects.toThrow("relay");
    expect(calls).toEqual(["on", "off"]);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
});
test("the loops are the three pumps", () => {
  expect(LOOPS).toEqual(["nutrientA", "nutrientB", "phDown"]);
});
@@ -0,0 +1,231 @@
/**
 * The dosing doors on the care routes: /care/dosing (state), /care/dosing/dose, /care/dosing/resume, /care/dosing/mode
 * (the owner's writes) and /care/mcp (the crew's tools). The limits live in src/doser.ts; this only says who may ask.
 * The pumps are the Pi's (src/arm-pumps.ts → src/dose-pumps.ts): /care/dosing/pump is the owner's setup of them (wire,
 * float, prime, calibrate, top off), never a dose. Readings are the log book's newest measurements. `fakeDoser`, whose
 * pumps do nothing (the log book says "simulated"), is for a relay with no pumps given.
 */
import type { IncomingMessage, ServerResponse } from "node:http";
import type { Cause, CareLog } from "./care-log.ts";
import { MEASURES, type Measure } from "./care-profile.ts";
import { Doser, LOOPS, type LoopId, type Mode, type Pump } from "./doser.ts";
import { FILL_TIMEOUT_MS, PUMP_LABEL, pumpRequest, type PumpHooks } from "./arm-pumps.ts";
import type { DosingView } from "./dose-pumps.ts";
export function fakeDoser(log: CareLog, file?: string, now?: () => number): Doser {
  const pump: Pump = { simulated: true, dose: async () => {} };
  return makeDoser(log, { nutrientA: pump, nutrientB: pump, phDown: pump }, file, now);
}
/** The controller over these pumps, reading the log book's newest measurements. */
export function makeDoser(log: CareLog, pumps: Record<LoopId, Pump>, file?: string, now?: () => number): Doser {
  return new Doser({
    pumps,
    latest: (kind: Measure) => {
      const m = log.entries().filter((e) => e.type === "measurement" && e.kind === kind).at(-1);
      return m && m.type === "measurement" ? { kind, value: m.value, at: m.at, source: m.source } : undefined;
    },
    calibrated: () => true,
    log,
    file,
    now,
  });
}
export interface DosingContext {
  doser: Doser;
  log: CareLog;
  /** Who asks, from the forge-signed identity; `id` keys the MCP's rate limit. */
  who: (req: IncomingMessage) => { owner: boolean; known: boolean; id?: string };
  readBody: (req: IncomingMessage, limit?: number) => Promise<Buffer>;
  /** A mutation is only taken from the page's own origin (relay.ts). */
  sameOrigin: (req: IncomingMessage) => boolean;
  /** The Pi's pumps; without them there is nothing to set up. */
  pumps?: PumpHooks;
}
const loopOf = (v: unknown): LoopId => {
  if (!LOOPS.includes(v as LoopId)) throw new Refused(`loop is one of ${LOOPS.join(", ")}`);
  return v as LoopId;
};
class Refused extends Error {}
/** Parse a JSON object body, capped by the bytes read. */
async function object(req: IncomingMessage, ctx: DosingContext): Promise<Record<string, unknown>> {
  const raw = await ctx.readBody(req, 4096); // capped by the bytes read, not by a header
  let v: unknown;
  if (!(req.headers["content-type"] ?? "").includes("json")) {
    // the page's buttons are forms
    v = Object.fromEntries([...new URLSearchParams(raw.toString("utf8"))].map(([k, x]) => [k, k === "ml" ? (x === "" ? undefined : Number(x)) : x]));
  } else
    try {
      v = JSON.parse(raw.toString("utf8") || "null");
    } catch {
      throw new Refused("send JSON");
    }
  if (!v || typeof v !== "object" || Array.isArray(v)) throw new Refused("send an object");
  return v as Record<string, unknown>;
}
/** True when the path was this module's and has been answered. */
export async function handleDosing(req: IncomingMessage, res: ServerResponse, pathname: string, ctx: DosingContext): Promise<boolean> {
  if (pathname !== "/care/dosing" && !pathname.startsWith("/care/dosing/") && pathname !== "/care/mcp") return false;
  const json = (status: number, body: unknown) => {
    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
    res.end(JSON.stringify(body));
  };
  if (pathname === "/care/mcp") {
    if (req.method !== "POST") return json(405, { error: "POST JSON-RPC here" }), true;
    if (!ctx.sameOrigin(req)) return json(403, { error: "not from this origin" }), true;
    // every call needs a verified identity: the log book and readings to read, the dosing tools only for the owner
    const caller = ctx.who(req);
    if (!caller.known) return json(401, { error: "sign in first: the care tools need a verified identity" }), true;
    if (!mcpLimit(ctx.doser).take(caller.id ?? "", Date.now())) return json(429, { error: `more than ${MCP_PER_MINUTE} calls a minute; wait a little` }), true;
    await mcp(req, res, ctx, caller.owner);
    return true;
  }
  const me = ctx.who(req);
  // dosing is the owner's to see and to change; a guest sees nothing
  if (!me.owner) return json(me.known ? 403 : 401, { error: "only the owner may use dosing" }), true;
  if (req.method === "GET" && pathname === "/care/dosing") return json(200, ctx.doser.status()), true;
  if (req.method === "GET" && pathname === "/care/dosing/pumps") {
    const v = ctx.pumps ? await ctx.pumps.read() : null;
    return v ? json(200, v) : json(502, { error: "the arm server did not answer" }), true;
  }
  if (req.method !== "POST") return json(405, { error: "POST here" }), true;
  if (!ctx.sameOrigin(req)) return json(403, { error: "only this page may change dosing" }), true;
  const form = !(req.headers["content-type"] ?? "").includes("json");
  const back = (msg?: string) => {
    res.writeHead(303, { location: msg ? `/care?error=${encodeURIComponent(msg)}` : "/care", "cache-control": "no-store" });
    res.end();
  };
  try {
    let result: unknown = { ok: true };
      
        junipercrew
        16d ago
        
      
      await object(req, ctx).catch(() => ({})) swallows every body error, including body too large, so an oversized resume still resumes. Resume needs no body, so don't read one. Or catch only the parse errors and let the 413 through.
    
    if (pathname === "/care/dosing/resume") {
      await object(req, ctx).catch(() => ({}));
      ctx.doser.resume("owner");
    } else if (pathname === "/care/dosing/mode") {
      const b = await object(req, ctx);
      ctx.doser.setMode(loopOf(b.loop), b.mode as Mode, "owner");
    } else if (pathname === "/care/dosing/dose") {
      const b = await object(req, ctx);
      const out = await ctx.doser.dose(loopOf(b.loop), "owner", b.ml === undefined ? undefined : (b.ml as number));
      if (!out.ok) return form ? back(out.reason) : json(409, { error: out.reason }), true;
      result = out;
    } else if (pathname === "/care/dosing/pump") {
      result = await setup(await object(req, ctx), ctx);
    } else return json(404, { error: "no such route" }), true;
    if (form) back();
    else json(200, result);
  } catch (err) {
    if (err instanceof Refused || (err instanceof Error && /^(mode|loop) is/.test(err.message))) form ? back((err as Error).message) : json(400, { error: (err as Error).message });
    else if ((err as Error).message === "body too large") json(413, { error: "too long" });
    else throw err;
  }
  return true;
}
/** One of the owner's setup actions, sent to the Pi; a prime or a top-off is written in the log book. */
async function setup(input: Record<string, unknown>, ctx: DosingContext): Promise<unknown> {
  if (!ctx.pumps) throw new Refused("no pumps are reachable from here");
  const body = pumpRequest(input);
  if (!body) throw new Refused("action is switch, float, prime, calibrate or fill");
  const a = await ctx.pumps.write(body, body.action === "fill" ? FILL_TIMEOUT_MS : 45_000);
  if (!a.ok) throw new Refused(a.error);
  const out = a.body as { stopped?: unknown; ms?: unknown; mlPerSec?: unknown } | null;
  const label = PUMP_LABEL[body.pump as keyof typeof PUMP_LABEL] ?? "";
  if (body.action === "fill") {
    const secs = Math.round(Number(out?.ms ?? 0) / 1000);
    ctx.log.add(out?.stopped === "full" ? { type: "action", what: "topoff", cause: "owner" } : { type: "observation", text: `Top-off stopped at its ${secs} s cap before the float said full: check the jug and the float` });
  } else if (body.action === "prime") ctx.log.add({ type: "observation", text: `Primed the ${label} pump for ${Number(body.ms) / 1000} s` });
  else if (body.action === "calibrate") ctx.log.add({ type: "observation", text: `Calibrated the ${label} pump: ${String(out?.mlPerSec)} ml/s` });
  return a.body;
}
/** Calls a minute per identity on /care/mcp: enough for an agent's loop, not for hammering the Pi. */
export const MCP_PER_MINUTE = 60;
/** A fixed one-minute window per key; the oldest keys are dropped past 1000 so the map stays small. */
export function rateLimit(perMinute: number) {
  const seen = new Map<string, { start: number; n: number }>();
  return {
    take(key: string, now: number): boolean {
      const w = seen.get(key);
      
        junipercrew
        16d ago
        
      
      The Pi's error text goes straight into /care?error=. It is escaped, but it is the tool's wording (gpioset failed). Translate it for the person here.
    
      if (!w || now - w.start >= 60_000) {
        seen.delete(key);
        seen.set(key, { start: now, n: 1 });
        if (seen.size > 1000) seen.delete(seen.keys().next().value!);
        return true;
      }
      return ++w.n <= perMinute;
    },
  };
}
/** One window per controller, so each app (and each test) counts its own calls. */
const mcpLimits = new WeakMap<Doser, ReturnType<typeof rateLimit>>();
const mcpLimit = (d: Doser) => mcpLimits.get(d) ?? (mcpLimits.set(d, rateLimit(MCP_PER_MINUTE)), mcpLimits.get(d)!);
/** The tools that show or change dosing, which is the owner's like the card on /care. */
const OWNER_TOOLS = new Set(["suggest_dose", "dose", "pumps"]);
const TOOLS = [
  { name: "readings", description: "The newest reading of each measure (pH, EC, temperatures, level) with its age.", inputSchema: { type: "object", properties: {} } },
  { name: "log", description: "The newest entries of the care log book.", inputSchema: { type: "object", properties: { limit: { type: "number" } } } },
  { name: "suggest_dose", description: "What a dosing loop would add now, or why not. Never doses.", inputSchema: { type: "object", properties: { loop: { type: "string", enum: [...LOOPS] } }, required: ["loop"] } },
  { name: "dose", description: "Dose a loop. Refused unless the owner put that loop in auto, and always bound by the per-dose and daily limits, the mixing wait and fresh readings.", inputSchema: { type: "object", properties: { loop: { type: "string", enum: [...LOOPS] }, ml: { type: "number" } }, required: ["loop"] } },
  { name: "pumps", description: "The dosing pumps on the Pi: each one's switch, measured ml/s and when it was calibrated, ml today, and whether the reservoir's high float says full. Read-only.", inputSchema: { type: "object", properties: {} } },
];
/** A minimal MCP over JSON-RPC: initialize, tools/list, tools/call. A dose here is the crew's; it cannot resume or change a mode. */
async function mcp(req: IncomingMessage, res: ServerResponse, ctx: DosingContext, owner: boolean) {
  const reply = (status: number, body: unknown) => {
    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
    res.end(JSON.stringify(body));
  };
  let msg: { id?: unknown; method?: unknown; params?: Record<string, unknown> };
  try {
    msg = await object(req, ctx);
  } catch (err) {
    return reply(400, { jsonrpc: "2.0", id: null, error: { code: -32700, message: (err as Error).message } });
  }
  const id = typeof msg.id === "number" || typeof msg.id === "string" ? msg.id : null;
  const ok = (result: unknown) => reply(200, { jsonrpc: "2.0", id, result });
  const text = (v: unknown, isError = false) => ok({ content: [{ type: "text", text: JSON.stringify(v) }], isError });
  switch (msg.method) {
    case "initialize":
      return ok({ protocolVersion: "2025-03-26", capabilities: { tools: {} }, serverInfo: { name: "arm-care", version: "1" } });
    case "tools/list":
      return ok({ tools: TOOLS });
    case "tools/call": {
      const args = (msg.params?.arguments ?? {}) as Record<string, unknown>;
      const cause: Cause = "crew";
      if (OWNER_TOOLS.has(String(msg.params?.name)) && !owner) return reply(403, { jsonrpc: "2.0", id, error: { code: -32001, message: "only the owner may use the dosing tools" } });
      try {
        switch (msg.params?.name) {
          case "pumps": {
            const v: DosingView | null = ctx.pumps ? await ctx.pumps.read() : null;
            return text(v ?? { error: "the Pi did not answer" }, !v);
          }
          case "readings": {
            const now = Date.now();
            return text(Object.fromEntries(MEASURES.map((k) => { const e = ctx.log.entries().filter((x) => x.type === "measurement" && x.kind === k).at(-1); return [k, e && e.type === "measurement" ? { value: e.value, at: e.at, ageMs: now - e.at, source: e.source } : null]; })));
          }
          case "log":
            return text(ctx.log.entries().slice(-Math.min(Math.max(Math.floor(Number(args.limit ?? 20)) || 20, 1), 100)));
          case "suggest_dose":
            return text(ctx.doser.suggest(loopOf(args.loop)));
          case "dose": {
            const out = await ctx.doser.dose(loopOf(args.loop), cause, args.ml === undefined ? undefined : (args.ml as number));
            return text(out, !out.ok);
          }
        }
      } catch (err) {
        return text({ error: (err as Error).message }, true);
      }
      return reply(200, { jsonrpc: "2.0", id, error: { code: -32602, message: "no such tool" } });
    }
    default:
      return reply(200, { jsonrpc: "2.0", id, error: { code: -32601, message: "no such method" } });
  }
}
@@ -9,10 +9,13 @@
import { MEASURES, type Measure } from "./care-profile.ts";
export const MAX_ENTRIES = 5000;
export const SENSOR_EVERY_MS = 3_600_000;
export const ACTIONS = ["sow", "water", "topoff", "change", "nutrients", "thin", "harvest", "airstone", "pumpcheck", "transplant", "done"] as const;
export const ACTIONS = ["sow", "water", "topoff", "change", "nutrients", "phdown", "thin", "harvest", "airstone", "pumpcheck", "transplant", "done"] as const;
export const PROBLEMS = ["bolting", "tip burn", "root rot", "algae", "yellowing", "leggy"] as const;
export const SYSTEMS = ["vertical tower", "DWC", "NFT", "Kratky", "ebb-and-flow"] as const;
export type Action = (typeof ACTIONS)[number];
/** Who or what made an action: the dose controller's rule, a crew agent, or the owner. */
export const CAUSES = ["rule", "crew", "owner"] as const;
export type Cause = (typeof CAUSES)[number];
/** What a sensor will also produce. */
export interface Reading {
@@ -31,7 +34,7 @@
export interface Transplant {
export type Entry = { id: number; at: number } & (
  | ({ type: "measurement" } & Omit<Reading, "at">)
  | { type: "action"; what: Action; amount?: number; ref?: string; transplant?: Transplant }
  | { type: "action"; what: Action; amount?: number; ref?: string; cause?: Cause; transplant?: Transplant }
  | { type: "observation"; text: string }
  | { type: "problem"; what: (typeof PROBLEMS)[number]; text?: string }
);
@@ -87,7 +90,8 @@
export function parseEntry(input: unknown, now = Date.now()): EntryBody {
        if (!/^[a-z0-9][a-z0-9-]*$/.test(ref!)) throw new LogError("ref is a reminder id");
        return { ...base, ref };
      }
      return { ...base, ...(e.amount !== undefined ? { amount: positive(e.amount, "amount", 100000) } : {}) };
      if (e.cause !== undefined && !CAUSES.includes(e.cause as Cause)) throw new LogError(`cause is one of ${CAUSES.join(", ")}`);
      return { ...base, ...(e.amount !== undefined ? { amount: positive(e.amount, "amount", 100000) } : {}), ...(e.cause !== undefined ? { cause: e.cause as Cause } : {}) };
    }
    case "observation":
      return { at, type: "observation", text: text(e.text, "text", 1000)! };
@@ -3,6 +3,10 @@
import { boltingWatch, currentStage, health, LABELS, ago, readings, reminders, snapshot, stageAt, stageHistory, totals, transplantPrompt, type Snapshot } from "./care-rules.ts";
import { ACTIONS, PROBLEMS, SYSTEMS, type Entry, type CareLog } from "./care-log.ts";
import { MEASURES, type Band, type Measure, type Profile } from "./care-profile.ts";
import type { Doser } from "./doser.ts";
import type { DosingView } from "./dose-pumps.ts";
import { renderPumps } from "./pumps-card.ts";
import { MODES } from "./doser.ts";
import { renderSignedIn, SIGNED_IN_STYLE, type SignedIn } from "./signed-in.ts";
import { esc } from "./story-markdown.ts";
@@ -28,6 +32,7 @@
h1 { margin: .5rem 0; } h2.first { margin-top: 0; } h2 { margin: 1.2rem 0 .5rem;
.health p { margin: .1rem 0; }
.panel { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: .6rem .8rem; margin: .6rem 0; }
ul.list { list-style: none; margin: 0; padding: 0; } ul.list li { display: flex; flex-wrap: wrap; gap: .4rem .8rem; align-items: center; justify-content: space-between; padding: .35rem 0; border-top: 1px solid var(--line); } ul.list li:first-child { border-top: 0; }
details { flex-basis: 100%; } details summary { cursor: pointer; color: var(--link); min-height: 44px; display: flex; align-items: center; } h3 { font-size: 1rem; margin: 1rem 0 .3rem; }
.late { color: var(--bad); font-weight: 600; } .dim { color: var(--dim); font-size: .9rem; }
button, select, input { font: inherit; min-height: 44px; border-radius: 8px; border: 1px solid var(--line); background: var(--bg); color: var(--fg); padding: 0 .7rem; box-sizing: border-box; }
button { background: var(--accent); color: var(--on-accent); border: 0; font-weight: 650; padding: 0 1rem; }
@@ -74,7 +79,7 @@
function describe(e: Entry): string {
    case "action":
      if (e.transplant) return `Transplant: ${e.transplant.system}, ${e.transplant.litres} L, ${e.transplant.sites} sites, pump ${e.transplant.pump ? "yes" : "no"}`;
      if (e.what === "done") return `Done: ${e.ref}`;
      return `${e.what}${e.amount ? ` ${e.amount}${e.what === "harvest" ? " g" : e.what === "nutrients" ? " ml" : ""}` : ""}`;
      return `${e.what}${e.amount ? ` ${e.amount}${e.what === "harvest" ? " g" : e.what === "nutrients" || e.what === "phdown" ? " ml" : ""}` : ""}`;
  }
}
@@ -88,6 +93,10 @@
export interface CareView {
  now: number;
  /** May write: the owner (or a run on one's own machine). */
  owner: boolean;
  /** The dosing card: the owner's only. */
  dosing?: ReturnType<Doser["status"]>;
  /** The Pi's pumps under the dosing card; null when the Pi did not answer. */
  pumps?: DosingView | null;
  signedIn: SignedIn | null;
  /** A refused form's message, shown at the top. */
  error?: string | null;
@@ -95,7 +104,7 @@
export interface CareView {
  probes?: string;
}
export function renderCare({ profile, log, now, owner, signedIn, error, probes = "" }: CareView): string {
export function renderCare({ profile, log, now, owner, signedIn, error, dosing, pumps, probes = "" }: CareView): string {
  const snap = snapshot(log);
  const spans = stageHistory(profile, snap.entries, snap.startedAt);
  const cur = currentStage(spans);
@@ -117,6 +126,19 @@
${spans.length === 1 ? `<form method="post" action="/care/log"><input type="hidd
</section>`
    : "";
  const dosingCard = dosing
    ? `<section class="panel" aria-labelledby="dosing" data-dosing><h2 id="dosing" style="margin-top:0">Dosing</h2>
${dosing.halted ? `<p class="alert" role="alert" data-halted>Dosing stopped: ${esc(dosing.halted)}</p>${post("/care/dosing/resume", {}, "Resume dosing")}` : ""}
${dosing.simulated ? `<p class="dim">No pumps are wired yet: a dose is only noted in the log book.</p>` : ""}
<ul class="list">${dosing.loops
        .map(
          (l) => `<li data-loop="${esc(l.id)}"><span><strong>${esc(l.label)}</strong> · ${esc(l.mode)}<br><span class="dim">${l.suggestion ? esc(l.suggestion.text) : esc(l.reason ?? "")} · today ${l.dosedTodayMl} of ${l.maxDayMl} ml, up to ${l.maxDoseMl} ml a dose</span></span>
<span>${l.suggestion && !dosing.halted ? post("/care/dosing/dose", { loop: l.id, ml: String(l.suggestion.ml) }, "Do it", "", `Do it: ${l.suggestion.text}`) : ""}
<form class="inline" method="post" action="/care/dosing/mode"><input type="hidden" name="loop" value="${esc(l.id)}"><select name="mode" aria-label="Mode for ${esc(l.label)}">${MODES.map((m) => `<option value="${m}"${m === l.mode ? " selected" : ""}>${m}</option>`).join("")}</select><button class="quiet">Set</button></form></span></li>`,
        )
        .join("")}</ul>${pumps !== undefined ? renderPumps(pumps) : ""}</section>`
    : "";
  const dueRows = due
    .map((d) => {
      const late = d.overdueMs > 0 && !d.snoozedUntil;
@@ -160,6 +182,7 @@
${error ? `<p class="alert" role="alert">${esc(error)}</p>` : ""}
${prompt ? `<p class="panel" data-prompt="transplant">${esc(prompt)}</p>` : ""}${bolt ? `<p class="panel" data-prompt="bolting">${esc(bolt)}</p>` : ""}
${quick}
${probes}
${dosingCard}
<h2>Reminders</h2><div class="panel"><ul class="list">${dueRows}</ul></div>
<h2>Metrics</h2>
<p class="dim">Typical ranges, not guaranteed. ${esc(profile.note)} Days since the last water change: ${sum.daysSinceChange ?? "none logged"}. Harvest so far: ${sum.harvestGrams} g. Light target ${profile.light.hours} h, warn above ${profile.light.warnAbove} h (bolting).</p>
@@ -6,11 +6,17 @@
import { LogError, type CareLog } from "./care-log.ts";
import { renderCare } from "./care-page.ts";
import { calibrateProbe, renderProbes, type ProbeCache } from "./care-probes.ts";
import type { Profile } from "./care-profile.ts";
import type { Doser } from "./doser.ts";
import type { DosingView } from "./dose-pumps.ts";
import type { SignedIn } from "./signed-in.ts";
export interface CareContext {
  profile: Profile;
  log: CareLog;
  /** The dosing controller; its card on the page is the owner's (the doors are src/care-dosing.ts). */
  doser?: Doser;
  /** The Pi's pumps for the dosing card: wiring, calibration, the float. */
  pumps?: () => Promise<DosingView | null>;
  /** null when the request may not write; the reader is told who they are for the page. */
  who: (req: IncomingMessage) => { owner: boolean; signedIn: SignedIn | null; known: boolean };
  readBody: (req: IncomingMessage, limit?: number) => Promise<Buffer>;
@@ -46,7 +52,7 @@
export async function handleCare(req: IncomingMessage, res: ServerResponse, path
  if (req.method === "GET" && pathname === "/care") {
    const probes = renderProbes(ctx.probes?.peek() ?? null, me.owner);
    send(200, "text/html; charset=utf-8", renderCare({ probes, profile: ctx.profile, log: ctx.log, now, owner: me.owner, signedIn: me.signedIn, error: new URL(req.url ?? "/", "http://x").searchParams.get("error")?.slice(0, 200) }));
    send(200, "text/html; charset=utf-8", renderCare({ probes, profile: ctx.profile, log: ctx.log, now, owner: me.owner, dosing: me.owner ? ctx.doser?.status() : undefined, pumps: me.owner && ctx.doser ? ((await ctx.pumps?.()) ?? null) : undefined, signedIn: me.signedIn, error: new URL(req.url ?? "/", "http://x").searchParams.get("error")?.slice(0, 200) }));
    return true;
  }
  if (req.method === "GET" && pathname === "/care/events") {
@@ -95,6 +95,26 @@
test("through the relay: a cross-site write is refused, a guest is 401, a plain
  expect(careLines({ stage: "seedling", health: { ok: true, lines: [] }, reminders: [], entries: [] })[0]).toContain("healthy");
});
test("through the terminal, a guest and a signed-in non-owner see nothing from /care dosing and /care pumps, and cannot set a pump up", async () => {
  const { port } = await start();
  const run = async (env: Record<string, string>, line: string) => {
    const printed: string[] = [];
    new Door("ws://127.0.0.1:1/live", {}, (l) => printed.push(l), null, null, null, null, null, null, null, null, null, null, null, null, careReader(env)).input(line);
    for (let i = 0; i < 100 && !printed.length; i++) await Bun.sleep(20);
    return printed;
  };
  for (const env of [terminal(port, null), terminal(port, "eve")]) {
    for (const line of ["/care dosing", "/care pumps", "/care prime phDown", "/care topoff", "/care dose phDown 2"]) {
      const out = await run(env, line);
      expect(out).toHaveLength(1);
      expect(out[0]).toMatch(/^error: only the owner may use dosing/);
    }
  }
  // the owner gets past the gate (the Pi here does not answer, and says so)
  const owner = await run(terminal(port, "trevato", "admin"), "/care dosing");
  expect(owner[0]).toMatch(/^Dosing running|^STOPPED/);
});
test("/probes through the relay: anyone reads, the owner calibrates, a web viewer hears it live, and a Pi that is down never delays /care", async () => {
  const view = (next: string | null) => ({ present: true, error: null, ph: null, ec: null, tempC: 21, tempSource: "default", calibratedAt: { ph: null, ec: null }, next, pending: next === "ph4" });
  const pi = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (req) => (new URL(req.url).pathname === "/probes/calibrate" ? Response.json(view("ph4")) : Response.json(view("ph7"))) });
@@ -5,14 +5,19 @@
import { ACTIONS, PROBLEMS } from "./care-log.ts";
import { MEASURES } from "./care-profile.ts";
import { LOOPS, MODES } from "./doser.ts";
import { DOSE_TIMEOUT_MS, FILL_TIMEOUT_MS, PUMP_LABEL } from "./arm-pumps.ts";
import { PUMP_IDS } from "./dose-pumps.ts";
export interface CareAsk {
  method: "GET" | "POST" | "DELETE";
  path: string;
  body?: Record<string, unknown>;
  /** How long to wait for the answer, when longer than a read: a dose or a top-off runs a pump first. */
  timeoutMs?: number;
}
export const CARE_USAGE = "usage: /care · /care log <ph|ec|waterTemp|airTemp|level|lightHours> <value> · /care did <action> [amount] · /care note <text> · /care problem <bolting|tip burn|root rot|algae|yellowing|leggy> [detail] · /care done <reminder> · /care snooze <reminder> [hours] · /care delete <entry id>";
export const CARE_USAGE = "usage: /care · /care log <ph|ec|waterTemp|airTemp|level|lightHours> <value> · /care did <action> [amount] · /care note <text> · /care problem <bolting|tip burn|root rot|algae|yellowing|leggy> [detail] · /care done <reminder> · /care snooze <reminder> [hours] · /care delete <entry id> · /care dosing · /care dose <nutrientA|nutrientB|phDown> [ml] · /care mode <loop> <off|suggest|auto> · /care resume · /care pumps · /care wire <pump> gpio <line> [low] | shelly <host> | none · /care prime <pump> [seconds] · /care calibrate <pump> <ml> · /care float <line|none> [low] [cap seconds] · /care topoff (dosing is the owner's; a pump is nutrientA, nutrientB, phDown or topOff)";
export const PROBES_USAGE = "usage: /probes · /probes calibrate <ph7|ph4|ec1413> [solution tempC] (owner)";
@@ -52,11 +57,79 @@
export function careCommand(words: string[], tail: string): CareAsk | { print: s
      return /^[a-z0-9-]{1,32}$/.test(a) && words.length <= 3 && (!b || Number.isFinite(num(b))) ? post("/care/reminder", { id: a, action: "snooze", hours: b ? num(b) : 24 }) : usage;
    case "delete":
      return /^\d{1,9}$/.test(a) && words.length === 2 ? { method: "DELETE", path: `/care/log/${a}`, body: {} } : usage;
    case "dosing":
      return words.length === 1 ? { method: "GET", path: "/care/dosing" } : usage;
    case "dose":
      return (LOOPS as readonly string[]).includes(a) && words.length <= 3 && (!b || Number.isFinite(num(b))) ? { ...post("/care/dosing/dose", { loop: a, ...(b ? { ml: num(b) } : {}) }), timeoutMs: DOSE_TIMEOUT_MS + 5000 } : usage;
    case "mode":
      return (LOOPS as readonly string[]).includes(a) && (MODES as readonly string[]).includes(b) && words.length === 3 ? post("/care/dosing/mode", { loop: a, mode: b }) : usage;
    case "resume":
      return words.length === 1 ? post("/care/dosing/resume", {}) : usage;
    case "pumps":
      return words.length === 1 ? { method: "GET", path: "/care/dosing/pumps" } : usage;
    case "wire": {
      const pump = (PUMP_IDS as readonly string[]).includes(a) ? a : null;
      const c = words[3] ?? "";
      if (!pump) return usage;
      if (b === "none" && words.length === 3) return pumpPost({ action: "switch", pump, switch: null });
      if (b === "gpio" && /^\d{1,2}$/.test(c) && words.length <= 5 && (words[4] === undefined || words[4] === "low")) return pumpPost({ action: "switch", pump, switch: { driver: "gpio", chip: "gpiochip0", line: Number(c), activeLow: words[4] === "low" } });
      if (b === "shelly" && c && words.length === 4) return pumpPost({ action: "switch", pump, switch: { driver: "shelly", host: c, gen: 2 } });
      return usage;
    }
    case "prime":
      return (PUMP_IDS as readonly string[]).includes(a) && words.length <= 3 && (!b || Number.isFinite(num(b))) ? pumpPost({ action: "prime", pump: a, sec: b ? num(b) : 10 }) : usage;
    case "calibrate":
      return (PUMP_IDS as readonly string[]).includes(a) && Number.isFinite(num(b)) && words.length === 3 ? pumpPost({ action: "calibrate", pump: a, ml: num(b) }) : usage;
    case "float": {
      if (a === "none" && words.length === 2) return pumpPost({ action: "float", line: "none" });
      if (!/^\d{1,2}$/.test(a) || words.length > 4) return usage;
      const rest = words.slice(2);
      const low = rest.includes("low");
      const cap = rest.find((w) => w !== "low");
      if (cap !== undefined && !/^\d{1,3}$/.test(cap)) return usage;
      return pumpPost({ action: "float", line: Number(a), activeLow: low, ...(cap ? { capSec: Number(cap) } : {}) });
    }
    case "topoff":
      return words.length === 1 ? pumpPost({ action: "fill" }) : usage;
    default:
      return usage;
  }
}
const pumpPost = (body: Record<string, unknown>): CareAsk => ({ method: "POST", path: "/care/dosing/pump", body, timeoutMs: body.action === "fill" ? FILL_TIMEOUT_MS + 5000 : 50_000 });
/** GET /care/dosing/pumps as lines. */
export function pumpLines(body: unknown): string[] {
  const b = (body ?? {}) as { pumps?: { id?: unknown; driver?: unknown; mlPerSec?: unknown; calibratedAt?: unknown; dosedTodayMl?: unknown }[]; float?: { line?: unknown; activeLow?: unknown } | null; full?: unknown; capSec?: unknown; error?: unknown };
  const lines = (b.pumps ?? []).map((p) => {
    const label = PUMP_LABEL[p.id as keyof typeof PUMP_LABEL] ?? String(p.id);
    const cal = typeof p.mlPerSec === "number" ? `${p.mlPerSec} ml/s${typeof p.calibratedAt === "number" ? ` (measured ${new Date(p.calibratedAt).toISOString().slice(0, 10)})` : ""}` : p.driver ? "not calibrated" : "not wired";
    return `  ${label} · ${p.driver ? String(p.driver) : "no switch"} · ${cal}${p.id === "topOff" ? "" : ` · today ${String(p.dosedTodayMl)} ml`}`;
  });
  lines.unshift("Pumps");
  lines.push(b.float ? `  high float on GPIO ${String(b.float.line)}${b.float.activeLow ? " (low)" : ""}: ${b.full === true ? "full" : b.full === false ? "not full" : "no answer"} · top-off cap ${String(b.capSec)} s` : "  no high float: top-off will not run");
  if (b.error) lines.push(`  the Pi says: ${String(b.error)}`);
  return lines;
}
/** What a setup action on the pumps answered, in a line. */
export function pumpSaid(body: unknown): string {
  const b = (body ?? {}) as { mlPerSec?: unknown; ms?: unknown; stopped?: unknown };
  if (typeof b.mlPerSec === "number") return `calibrated: ${b.mlPerSec} ml/s`;
  if (b.stopped === "full") return `top-off: full after ${Math.round(Number(b.ms) / 1000)} s`;
  if (b.stopped === "cap") return `top-off: stopped at the cap after ${Math.round(Number(b.ms) / 1000)} s, not full; check the jug and the float`;
  if (typeof b.ms === "number") return `primed for ${b.ms / 1000} s: measure the cup, then /care calibrate <pump> <ml>`;
  return "pumps: done";
}
/** GET /care/dosing as lines. */
export function dosingLines(body: unknown): string[] {
  const b = (body ?? {}) as { halted?: unknown; simulated?: unknown; loops?: { label?: unknown; mode?: unknown; suggestion?: { text?: unknown } | null; reason?: unknown; dosedTodayMl?: unknown; maxDayMl?: unknown }[] };
  const lines = [b.halted ? `STOPPED: ${String(b.halted)} (/care resume)` : "Dosing running", ...(b.simulated ? ["  no pumps wired: a dose is only noted in the log book"] : [])];
  for (const l of b.loops ?? []) lines.push(`  ${String(l.label)} · ${String(l.mode)} · ${l.suggestion ? String(l.suggestion.text) : String(l.reason ?? "")} · today ${String(l.dosedTodayMl)}/${String(l.maxDayMl)} ml`);
  return lines;
}
const day = (at: number) => new Date(at).toISOString().replace("T", " ").slice(0, 16);
/** GET /care/api as lines: the stage, the health strip, what is due, and the latest entries with their ids. */
@@ -0,0 +1,296 @@
import { afterEach, describe, expect, test } from "bun:test";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { armPumps, cachedRead, pumpRequest, readDosing, type PumpHooks } from "./arm-pumps.ts";
import { CareLog } from "./care-log.ts";
import { BUILT_IN_DIR, loadProfiles } from "./care-profile.ts";
import { careCommand, pumpLines, pumpSaid } from "./care-terminal.ts";
import { DosePumps, MAX_DAY_ML, MAX_RUN_MS, PumpError } from "./dose-pumps.ts";
import { Doser, PumpRefused } from "./doser.ts";
import { FeetechBus } from "./bus.ts";
import { FakeBus } from "./fake-bus.ts";
import { sign } from "./identity.ts";
import type { DriverConfig, Switch } from "./light-switch.ts";
import { Lobby } from "./lobby.ts";
import { renderPumps } from "./pumps-card.ts";
import { startRelay, type RunningRelay } from "./relay.ts";
import { startServer, type RunningServer } from "./server.ts";
/** Fake hardware: every switch by its GPIO line (or host), what it was told, and a float the test sets. */
function rig(dir = mkdtempSync(join(tmpdir(), "so101-pumps-"))) {
  let t = 1_800_000_000_000;
  const calls: string[] = [];
  const state: Record<string, boolean> = {};
  const fail: Record<string, "on" | "off"> = {};
  let full = false;
  let fillAfterMs = Infinity;
  let onAt = 0;
  const key = (c: DriverConfig) => (c.driver === "gpio" ? `gpio${c.line}` : c.driver === "shelly" ? c.host : "usb");
  const make = (c: DriverConfig): Switch => {
    const k = key(c);
    return {
      on: async () => {
        if (fail[k] === "on") throw new Error("relay stuck");
        calls.push(`${k} on`);
        state[k] = true;
        onAt = t;
      },
      off: async () => {
        if (fail[k] === "off") throw new Error("relay welded");
        calls.push(`${k} off`);
        state[k] = false;
      },
      // the float: wet once the top-off pump has run long enough
      state: async () => full || (state.gpio5 === true && t - onAt >= fillAfterMs),
    };
  };
  const sleep = async (ms: number) => void (t += ms);
  const pumps = new DosePumps({ file: join(dir, "dose-pumps.json"), now: () => t, sleep, make });
  return { dir, pumps, calls, state, fail, make, sleep, now: () => t, advance: (ms: number) => (t += ms), setFull: (v: boolean) => (full = v), fillAfter: (ms: number) => (fillAfterMs = ms) };
}
const refusal = async (p: Promise<unknown>) => {
  try {
    await p;
  } catch (err) {
    return err as PumpError;
  }
  throw new Error("expected a refusal");
};
describe("the Pi's pumps", () => {
  test("an unwired or uncalibrated pump refuses a dose before anything is switched", async () => {
    const r = rig();
    const e = await refusal(r.pumps.act({ action: "dose", pump: "phDown", ml: 2 }));
    expect(e).toBeInstanceOf(PumpError);
    expect(e.refused).toBe(true);
    expect(e.message).toContain("no switch");
    await r.pumps.act({ action: "switch", pump: "phDown", switch: { driver: "gpio", line: 17 } });
    r.calls.length = 0;
    const u = await refusal(r.pumps.act({ action: "dose", pump: "phDown", ml: 2 }));
    expect(u.refused).toBe(true);
    expect(u.message).toContain("not calibrated");
    expect(r.calls).toEqual([]);
    expect(r.pumps.dosedToday("phDown")).toBe(0);
  });
  test("prime into a cup, type the ml, and a dose runs for ml ÷ ml/s", async () => {
    const r = rig();
    await r.pumps.act({ action: "switch", pump: "nutrientA", switch: { driver: "gpio", line: 22, activeLow: true } });
    expect((await refusal(r.pumps.act({ action: "calibrate", pump: "nutrientA", ml: 12 }))).message).toContain("prime");
    const t0 = r.now();
    expect(await r.pumps.act({ action: "prime", pump: "nutrientA", ms: 10_000 })).toEqual({ ok: true, ms: 10_000 });
    expect(r.now() - t0).toBe(10_000);
    expect(r.calls.slice(-2)).toEqual(["gpio22 on", "gpio22 off"]);
    expect(await r.pumps.act({ action: "calibrate", pump: "nutrientA", ml: 12 })).toEqual({ ok: true, mlPerSec: 1.2 });
    const t1 = r.now();
    expect(await r.pumps.act({ action: "dose", pump: "nutrientA", ml: 6 })).toEqual({ ok: true, ml: 6, ms: 5000 });
    expect(r.now() - t1).toBe(5000);
    expect(r.state.gpio22).toBe(false);
    const v = await r.pumps.view();
    expect(v.pumps.find((p) => p.id === "nutrientA")).toMatchObject({ driver: "gpio", mlPerSec: 1.2, dosedTodayMl: 6 });
    // a calibration that is not a dosing pump's flow, or an old prime, is refused
    await r.pumps.act({ action: "prime", pump: "nutrientA", ms: 1000 });
    expect((await refusal(r.pumps.act({ action: "calibrate", pump: "nutrientA", ml: 900 }))).message).toContain("measure again");
    r.advance(3_600_001);
    expect((await refusal(r.pumps.act({ action: "calibrate", pump: "nutrientA", ml: 1 }))).message).toContain("prime");
  });
  test("the Pi's backstop: one run past 60 s or a day past 100 ml is refused, whatever the controller asks", async () => {
    const r = rig();
    await r.pumps.act({ action: "switch", pump: "phDown", switch: { driver: "gpio", line: 17 } });
    await r.pumps.act({ action: "prime", pump: "phDown", ms: 10_000 });
    await r.pumps.act({ action: "calibrate", pump: "phDown", ml: 10 }); // 1 ml/s
    const long = await refusal(r.pumps.act({ action: "dose", pump: "phDown", ml: MAX_RUN_MS / 1000 + 1 }));
    expect(long.refused).toBe(true);
    expect(long.message).toContain("60 s");
    for (let i = 0; i < 2; i++) await r.pumps.act({ action: "dose", pump: "phDown", ml: 50 });
    const day = await refusal(r.pumps.act({ action: "dose", pump: "phDown", ml: 1 }));
    expect(day.message).toContain(`${MAX_DAY_ML} ml`);
    r.advance(86_400_001);
    expect(await r.pumps.act({ action: "dose", pump: "phDown", ml: 1 })).toMatchObject({ ok: true });
  });
  test("a switch that fails once on is switched off anyway, and it is a failure, not a refusal", async () => {
    const r = rig();
    await r.pumps.act({ action: "switch", pump: "phDown", switch: { driver: "gpio", line: 17 } });
    r.fail.gpio17 = "on";
    const e = await refusal(r.pumps.act({ action: "prime", pump: "phDown", ms: 2000 }));
    expect(e.refused).toBe(false);
    expect(r.calls.at(-1)).toBe("gpio17 off");
    expect((await r.pumps.view()).running).toBeNull();
  });
  test("top-off runs to the high float, stops at the cap, and will not run without a float", async () => {
    const r = rig();
    await r.pumps.act({ action: "switch", pump: "topOff", switch: { driver: "gpio", line: 5 } });
    expect((await refusal(r.pumps.act({ action: "fill" }))).message).toContain("float");
    await r.pumps.act({ action: "float", float: { line: 6 }, capSec: 30 });
    r.fillAfter(4000);
    const filled = (await r.pumps.act({ action: "fill" })) as { stopped: string; ms: number };
    expect(filled.stopped).toBe("full");
    expect(filled.ms).toBeLessThan(6000);
    expect(r.state.gpio5).toBe(false);
    r.fillAfter(Infinity);
    expect(await r.pumps.act({ action: "fill" })).toMatchObject({ stopped: "cap", ms: 30_000 });
    expect(r.state.gpio5).toBe(false);
    expect((await refusal(r.pumps.act({ action: "float", capSec: 9999 }))).message).toContain("cap");
    expect((await refusal(r.pumps.act({ action: "dose", pump: "topOff", ml: 5 }))).message).toContain("float");
  });
  test("bad input is refused with a sentence; a USB port is not a pump's switch; a new switch clears the calibration", async () => {
    const r = rig();
    for (const bad of [null, [], { action: "nope" }, { action: "dose", pump: "rum", ml: 1 }, { action: "prime", pump: "phDown", ms: 999_999 }, { action: "switch", pump: "phDown", switch: { driver: "uhubctl", hub: "1-1", port: 2 } }, { action: "dose", pump: "phDown", ml: 1, extra: 1 }]) {
      const e = await refusal(r.pumps.act(bad));
      expect(e.refused).toBe(true);
    }
    await r.pumps.act({ action: "switch", pump: "phDown", switch: { driver: "gpio", line: 17 } });
    await r.pumps.act({ action: "prime", pump: "phDown", ms: 10_000 });
    await r.pumps.act({ action: "calibrate", pump: "phDown", ml: 10 });
    await r.pumps.act({ action: "switch", pump: "phDown", switch: { driver: "shelly", host: "192.168.1.41" } });
    expect((await r.pumps.view()).pumps.find((p) => p.id === "phDown")).toMatchObject({ driver: "shelly", mlPerSec: null });
  });
  test("kept across a restart, and every wired pump is switched off on boot", async () => {
    const r = rig();
    try {
      await r.pumps.act({ action: "switch", pump: "nutrientB", switch: { driver: "gpio", line: 23 } });
      await r.pumps.act({ action: "prime", pump: "nutrientB", ms: 5000 });
      await r.pumps.act({ action: "calibrate", pump: "nutrientB", ml: 4 });
      r.state.gpio23 = true; // as if the Pi went down mid-dose
      const again = new DosePumps({ file: join(r.dir, "dose-pumps.json"), now: r.now, sleep: r.sleep, make: r.make });
      await again.boot();
      expect(r.state.gpio23).toBe(false);
      expect((await again.view()).pumps.find((p) => p.id === "nutrientB")).toMatchObject({ driver: "gpio", mlPerSec: 0.8 });
    } finally {
      rmSync(r.dir, { recursive: true, force: true });
    }
  });
});
describe("the relay's side", () => {
  test("a 409 from the Pi is PumpRefused (nothing ran); anything else is a failure", async () => {
    const answers: Parameters<PumpHooks["write"]>[0][] = [];
    let next: Awaited<ReturnType<PumpHooks["write"]>> = { ok: false, status: 409, error: "not calibrated" };
    const p = armPumps({ read: async () => null, write: async (b) => (answers.push(b), next) });
    expect(p.phDown.dose(3)).rejects.toBeInstanceOf(PumpRefused);
    next = { ok: false, status: 500, error: "relay stuck" };
    const err = await p.phDown.dose(3).catch((e: Error) => e);
    expect(err).not.toBeInstanceOf(PumpRefused);
    next = { ok: true, body: {} };
    await p.nutrientA.dose(2);
    expect(answers.at(-1)).toEqual({ action: "dose", pump: "nutrientA", ml: 2 });
  });
  test("the owner's forms never become a dose; the Pi's answer is read field by field", () => {
    expect(pumpRequest({ action: "dose", pump: "phDown", ml: "50" })).toBeNull();
    expect(pumpRequest({ action: "switch", pump: "phDown", driver: "gpio", line: "17", activeLow: "on" })).toEqual({ action: "switch", pump: "phDown", switch: { driver: "gpio", chip: "gpiochip0", line: 17, activeLow: true } });
    expect(pumpRequest({ action: "prime", pump: "phDown", sec: "10" })).toEqual({ action: "prime", pump: "phDown", ms: 10_000 });
    expect(pumpRequest({ action: "float", line: "", capSec: "60" })).toEqual({ action: "float", float: null, capSec: 60 });
    const v = readDosing({ pumps: [{ id: "phDown", driver: "<script>", mlPerSec: 1 }, { id: "rum" }], error: "a\u0000<b>" })!;
    expect(v.pumps).toEqual([{ id: "phDown", driver: null, mlPerSec: 1, calibratedAt: null, dosedTodayMl: 0 }]);
    expect(renderPumps({ ...v, error: "<b>x</b>" })).not.toContain("<b>x</b>");
    expect(readDosing("nope")).toBeNull();
    expect(renderPumps(null)).toContain("did not answer");
  });
  test("the terminal's pump commands", () => {
    expect(careCommand(["wire", "phDown", "gpio", "17", "low"], "")).toMatchObject({ method: "POST", path: "/care/dosing/pump", body: { action: "switch", pump: "phDown", switch: { driver: "gpio", line: 17, activeLow: true } } });
    expect(careCommand(["prime", "nutrientA"], "")).toMatchObject({ body: { action: "prime", pump: "nutrientA", sec: 10 } });
    expect(careCommand(["calibrate", "nutrientA", "11.5"], "")).toMatchObject({ body: { action: "calibrate", pump: "nutrientA", ml: 11.5 } });
    expect(careCommand(["float", "27", "low", "90"], "")).toMatchObject({ body: { action: "float", line: 27, activeLow: true, capSec: 90 } });
    expect(careCommand(["topoff"], "")).toMatchObject({ body: { action: "fill" }, timeoutMs: expect.any(Number) });
    expect(careCommand(["pumps"], "")).toEqual({ method: "GET", path: "/care/dosing/pumps" });
    for (const bad of [["wire", "rum", "gpio", "1"], ["calibrate", "phDown"], ["float", "x"]]) expect(careCommand(bad, "")).toHaveProperty("print");
    expect(pumpSaid({ ok: true, mlPerSec: 1.2 })).toBe("calibrated: 1.2 ml/s");
    expect(pumpLines({ pumps: [{ id: "phDown", driver: "gpio", mlPerSec: 1, dosedTodayMl: 3 }], float: null })[1]).toContain("pH down · gpio · 1 ml/s · today 3 ml");
  });
});
describe("end to end: the page's relay, the arm server and a pump", () => {
  const KEY = "k".repeat(64);
  const owner = () => {
    const identity = `id-trevato|trevato|admin|${Date.now() + 600_000}`;
    return { "x-forge-identity": identity, "x-forge-signature": sign(identity, KEY), "content-type": "application/json" };
  };
  let relay: RunningRelay | undefined;
  let server: RunningServer | undefined;
  let lobby: Lobby | undefined;
  let dir = "";
  afterEach(async () => {
    await relay?.close();
    server?.close();
    lobby?.close();
    if (dir) rmSync(dir, { recursive: true, force: true });
    relay = server = lobby = undefined;
  });
  test("the owner wires and calibrates a pump from /care; a dose goes through the controller to the Pi; a browser cannot reach the Pi's pumps", async () => {
    const r = rig();
    dir = r.dir;
    server = await startServer(new FeetechBus(new FakeBus([1, 2])), { host: "127.0.0.1", port: 0, ids: [1, 2], posesFile: join(dir, "poses.json"), dosePumps: r.pumps });
    lobby = new Lobby({ identityKey: KEY, adminFile: join(dir, "admin.json"), countsFile: join(dir, "visitors.json") });
    const log = new CareLog();
    const profile = loadProfiles(BUILT_IN_DIR).find((p) => p.id === "spinach")!;
    relay = await startRelay({ port: 0, simulation: `http://127.0.0.1:${server.port}`, lobby, care: { log, profile } });
    const base = `http://127.0.0.1:${relay.port}`;
    const setup = (body: unknown) => fetch(`${base}/care/dosing/pump`, { method: "POST", headers: owner(), body: JSON.stringify(body) });
    // nobody but the relay may ask the Pi: a browser's /grow/dosing, owner or not, is no route
    for (const headers of [owner(), {}]) {
      expect((await fetch(`${base}/grow/dosing`, { headers })).status).toBe(404);
      expect((await fetch(`${base}/grow/dosing`, { method: "POST", headers, body: JSON.stringify({ action: "dose", pump: "phDown", ml: 50 }) })).status).toBe(404);
    }
    // and a dose is not a setup action
    expect((await setup({ action: "dose", pump: "phDown", ml: 50 })).status).toBe(400);
    // a guest cannot set up
    expect((await fetch(`${base}/care/dosing/pump`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ action: "fill" }) })).status).toBe(401);
    expect((await setup({ action: "switch", pump: "phDown", driver: "gpio", line: 17 })).status).toBe(200);
    // before calibration a dose is refused by the pump, not counted, and dosing does not halt
    log.add({ type: "measurement", kind: "ph", value: 7.2 });
    const early = await fetch(`${base}/care/dosing/dose`, { method: "POST", headers: owner(), body: JSON.stringify({ loop: "phDown" }) });
    expect(early.status).toBe(409);
    expect(((await early.json()) as { error: string }).error).toContain("not calibrated");
    expect(r.calls).not.toContain("gpio17 on");
    expect((await setup({ action: "prime", pump: "phDown", sec: 10 })).status).toBe(200);
    const cal = await setup({ action: "calibrate", pump: "phDown", ml: 5 });
    expect(await cal.json()).toEqual({ ok: true, mlPerSec: 0.5 });
    r.calls.length = 0;
    const t0 = r.now();
    const did = await fetch(`${base}/care/dosing/dose`, { method: "POST", headers: owner(), body: JSON.stringify({ loop: "phDown" }) });
    expect(did.status).toBe(200);
    const ml = ((await did.json()) as { ml: number }).ml;
    expect(r.calls).toEqual(["gpio17 on", "gpio17 off"]);
    expect(r.now() - t0).toBe(Math.round((ml / 0.5) * 1000));
    expect(log.entries().at(-1)).toMatchObject({ type: "action", what: "phdown", amount: ml, cause: "owner" });
    expect(relay && (await (await fetch(`${base}/care/dosing`, { headers: owner() })).json())).toMatchObject({ halted: null, simulated: false });
    // the card shows the pump, calibrated
    const page = await (await fetch(`${base}/care`, { headers: owner() })).text();
    expect(page).toContain('data-pump="phDown"');
    expect(page).toContain("0.5 ml/s");
    // and the crew reads the pumps through the MCP
    expect((await fetch(`${base}/care/mcp`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "pumps", arguments: {} } }) })).status).toBe(401);
    const mcp = await fetch(`${base}/care/mcp`, { method: "POST", headers: owner(), body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "pumps", arguments: {} } }) });
    const said = JSON.parse(((await mcp.json()) as { result: { content: { text: string }[] } }).result.content[0]!.text) as { pumps: { id: string; mlPerSec: number | null }[] };
    expect(said.pumps.find((p) => p.id === "phDown")!.mlPerSec).toBe(0.5);
  });
});
test("Doser over armPumps keeps its own limits in front of the Pi", async () => {
  const asked: unknown[] = [];
  const log = new CareLog(undefined, () => 1_800_000_000_000);
  const doser = new Doser({ pumps: armPumps({ read: async () => null, write: async (b) => (asked.push(b), { ok: true, body: {} }) }), latest: () => ({ kind: "ph", value: 7.2, at: 1_800_000_000_000, source: "sensor" }), calibrated: () => true, log, loops: { phDown: { mode: "auto" } }, now: () => 1_800_000_000_000 });
  expect(await doser.dose("phDown", "crew", 50)).toMatchObject({ ok: false, reason: expect.stringContaining("per-dose") });
  expect(asked).toEqual([]);
});
test("a Pi that is down holds the page's first read of the pumps for 300 ms at most", async () => {
  const c = cachedRead(() => new Promise(() => {}));
  const began = performance.now();
  expect(await c.read()).toBeNull();
  expect(performance.now() - began).toBeLessThan(450);
});
@@ -0,0 +1,362 @@
/**
 * The dosing pumps on the Pi: three peristaltic pumps (nutrient A, nutrient B, pH down) and the top-off pump, each a
 * `Switch` (a GPIO line to a relay or MOSFET board, or a Shelly plug; src/light-switch.ts), with a measured ml/s.
 *   dose       ml → seconds with the pump's calibration, then on, wait, off; refused before anything runs when the pump
 *              has no switch, no calibration, or the ask is past the Pi's own backstop (per run and per day)
 *   prime      run a pump for a few seconds into a measuring cup (and fill its tube)
 *   calibrate  the ml the cup caught on the last prime becomes the pump's ml/s
 *   fill       top-off: the fresh-water pump runs until the high float says full or the time cap passes (doser.ts `topOff`)
 * The limits that decide whether to dose live in the controller (src/doser.ts); the backstop here is for a controller
 * that is wrong. A pump is switched off on boot and in every `finally`, so a crash or a throw never leaves one running.
 * Settings are kept beside the arm's other data.
 */
import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";
import { topOff } from "./doser.ts";
import { makeSwitch, parseDriver, SwitchError, type Deps, type DriverConfig, type Switch } from "./light-switch.ts";
export const DOSE_PUMPS = ["nutrientA", "nutrientB", "phDown"] as const;
export const PUMP_IDS = [...DOSE_PUMPS, "topOff"] as const;
export type PumpId = (typeof PUMP_IDS)[number];
type DosePumpId = (typeof DOSE_PUMPS)[number];
/** The Pi's backstop, whatever the controller asks. */
export const MAX_RUN_MS = 60_000;
export const MAX_DAY_ML = 100;
export const PRIME_MS = { min: 1_000, max: 30_000 } as const;
/** A calibration answers the prime just before it. */
export const PRIME_FRESH_MS = 3_600_000;
export const ML_PER_SEC = { min: 0.01, max: 50 } as const;
export const TOP_OFF_CAP = { min: 5, max: 600, default: 120 } as const;
export class PumpError extends Error {
  /** True when nothing was switched on: the caller may treat it as a refusal, not a failure. */
  readonly refused: boolean;
  constructor(message: string, refused: boolean) {
    super(message);
    this.refused = refused;
  }
}
export interface FloatConfig {
  chip: string;
  line: number;
  activeLow: boolean;
}
interface PumpState {
  driver: DriverConfig | null;
  mlPerSec: number | null;
  calibratedAt: number | null;
}
interface Stored {
  pumps: Record<PumpId, PumpState>;
  /** The high float in the reservoir: top-off stops on it. */
  float: FloatConfig | null;
  capSec: number;
  /** Runs in the last day, for the backstop. */
  doses: { pump: DosePumpId; at: number; ml: number }[];
  /** The last prime, which a calibration answers. */
  primed: { pump: PumpId; ms: number; at: number } | null;
}
export interface PumpView {
  id: PumpId;
  driver: string | null;
  mlPerSec: number | null;
  calibratedAt: number | null;
  dosedTodayMl: number;
}
export interface DosingView {
  pumps: PumpView[];
  float: FloatConfig | null;
  /** Wet (full), dry, or null when there is no float or it did not answer. */
  full: boolean | null;
  capSec: number;
  primed: { pump: PumpId; ms: number; at: number } | null;
  running: PumpId | null;
  maxRunMs: number;
  maxDayMl: number;
  error: string | null;
}
export interface DosePumpsOptions {
  file: string;
  now?: () => number;
  sleep?: (ms: number) => Promise<void>;
  make?: (config: DriverConfig) => Switch;
  deps?: Deps;
}
const empty = (): PumpState => ({ driver: null, mlPerSec: null, calibratedAt: null });
const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
const pumpOf = (v: unknown): PumpId => {
  if (!PUMP_IDS.includes(v as PumpId)) throw new PumpError(`pump is one of ${PUMP_IDS.join(", ")}`, true);
  return v as PumpId;
};
/** A pump's switch: a GPIO line or a Shelly plug. A USB port cannot carry a 12 V pump, so uhubctl is not one. */
export function parsePumpDriver(input: unknown): DriverConfig {
  const d = parseDriver(input);
  if (d.driver === "uhubctl") throw new SwitchError("a pump's switch is a GPIO relay or MOSFET, or a Shelly plug");
  return d;
}
export function parseFloatLine(input: unknown): FloatConfig {
  if (!isObj(input)) throw new PumpError("the float is an object", true);
  const d = parseDriver({ driver: "gpio", ...input });
  if (d.driver !== "gpio") throw new PumpError("the float is a GPIO line", true);
  return { chip: d.chip, line: d.line, activeLow: d.activeLow };
}
export class DosePumps {
  private s: Stored = { pumps: Object.fromEntries(PUMP_IDS.map((p) => [p, empty()])) as Record<PumpId, PumpState>, float: null, capSec: TOP_OFF_CAP.default, doses: [], primed: null };
  private running: PumpId | null = null;
  private error: string | null = null;
  private lastFull: boolean | null = null;
  private readonly now: () => number;
  private readonly sleep: (ms: number) => Promise<void>;
  private readonly make: (config: DriverConfig) => Switch;
  private readonly o: DosePumpsOptions;
  constructor(o: DosePumpsOptions) {
    this.o = o;
    this.now = o.now ?? Date.now;
    this.sleep = o.sleep ?? ((ms) => new Promise<void>((r) => setTimeout(r, ms)));
    this.make = o.make ?? ((c) => makeSwitch(c, o.deps));
    this.load();
  }
  private sw(id: PumpId): Switch | null {
    const d = this.s.pumps[id].driver;
    return d ? this.make(d) : null;
  }
  private floatSwitch(): Switch | null {
    return this.s.float ? this.make({ driver: "gpio", ...this.s.float }) : null;
  }
  /** On start-up: every wired pump off, whatever it was doing when the Pi went down. */
  async boot(): Promise<void> {
    for (const id of PUMP_IDS) {
      try {
        await this.sw(id)?.off();
      } catch (err) {
        this.error = `${id} would not switch off: ${(err as Error).message}`;
        console.error(`dosing: ${this.error}`);
      }
    }
  }
  dosedToday(id: PumpId): number {
    const since = this.now() - 86_400_000;
    return this.s.doses.filter((d) => d.pump === id && d.at > since).reduce((n, d) => n + d.ml, 0);
  }
  async view(): Promise<DosingView> {
    const f = this.floatSwitch();
    if (f && !this.running) {
      try {
        this.lastFull = await f.state();
      } catch {
        this.lastFull = null;
      }
    } else if (!f) this.lastFull = null;
    return {
      pumps: PUMP_IDS.map((id) => ({ id, driver: this.s.pumps[id].driver?.driver ?? null, mlPerSec: this.s.pumps[id].mlPerSec, calibratedAt: this.s.pumps[id].calibratedAt, dosedTodayMl: this.dosedToday(id) })),
      float: this.s.float,
      full: this.lastFull,
      capSec: this.s.capSec,
      primed: this.s.primed,
      running: this.running,
      maxRunMs: MAX_RUN_MS,
      maxDayMl: MAX_DAY_ML,
      error: this.error,
    };
  }
  /** One request, one action: `switch`, `float`, `dose`, `prime`, `calibrate` or `fill`. Throws PumpError naming what is wrong. */
  async act(body: unknown): Promise<unknown> {
    if (!isObj(body)) throw new PumpError("send an object", true);
    const { action, pump, ...rest } = body;
    const only = (...keys: string[]) => {
      const extra = Object.keys(rest).find((k) => !keys.includes(k));
      if (extra) throw new PumpError(`no field "${extra.slice(0, 40)}"`, true);
    };
    try {
      switch (action) {
        case "switch": {
          only("switch");
          const id = pumpOf(pump);
          const driver = rest.switch === null ? null : parsePumpDriver(rest.switch);
          if (this.running === id) throw new PumpError(`the ${id} pump is running`, true);
          // the new switch must answer (off) before it is kept; the old one is let go off
          if (driver) await this.make(driver).off();
          await this.sw(id)?.off().catch(() => {});
          // a new switch is a new pump as far as its flow goes: calibrate again
          this.s.pumps[id] = { driver, mlPerSec: null, calibratedAt: null };
          this.save();
          return { ok: true };
        }
        case "float": {
          only("float", "capSec");
          if (pump !== undefined) throw new PumpError("the float is not a pump's", true);
          if (rest.float !== undefined) this.s.float = rest.float === null ? null : parseFloatLine(rest.float);
          if (rest.capSec !== undefined) {
            const c = rest.capSec;
            if (typeof c !== "number" || !Number.isInteger(c) || c < TOP_OFF_CAP.min || c > TOP_OFF_CAP.max) throw new PumpError(`the top-off cap is a whole number of seconds from ${TOP_OFF_CAP.min} to ${TOP_OFF_CAP.max}`, true);
            this.s.capSec = c;
          }
          this.save();
          return { ok: true };
        }
        case "dose": {
          only("ml");
          const id = pumpOf(pump);
          if (id === "topOff") throw new PumpError("top-off fills to the float; it does not dose", true);
          return await this.dose(id, rest.ml);
        }
        case "prime": {
          only("ms");
          const id = pumpOf(pump);
          const ms = rest.ms;
          if (typeof ms !== "number" || !Number.isInteger(ms) || ms < PRIME_MS.min || ms > PRIME_MS.max) throw new PumpError(`prime for a whole number of ms from ${PRIME_MS.min} to ${PRIME_MS.max}`, true);
          const sw = this.ready(id);
          await this.runFor(id, sw, ms);
          this.s.primed = { pump: id, ms, at: this.now() };
          this.save();
          return { ok: true, ms };
        }
        case "calibrate": {
          only("ml");
          const id = pumpOf(pump);
          const ml = rest.ml;
          const p = this.s.primed;
          if (!p || p.pump !== id || this.now() - p.at > PRIME_FRESH_MS) throw new PumpError(`prime the ${id} pump into a measuring cup first, then say how many ml it caught`, true);
          if (typeof ml !== "number" || !Number.isFinite(ml) || ml <= 0 || ml > 1000) throw new PumpError("ml is a number above 0, up to 1000", true);
          const rate = Math.round((ml / (p.ms / 1000)) * 1000) / 1000;
          if (rate < ML_PER_SEC.min || rate > ML_PER_SEC.max) throw new PumpError(`${rate} ml/s is not a dosing pump's flow (${ML_PER_SEC.min}–${ML_PER_SEC.max}); measure again`, true);
          this.s.pumps[id] = { ...this.s.pumps[id], mlPerSec: rate, calibratedAt: this.now() };
          this.s.primed = null;
          this.save();
          return { ok: true, mlPerSec: rate };
        }
        case "fill": {
          only();
          if (pump !== undefined && pump !== "topOff") throw new PumpError("fill runs the top-off pump", true);
          return await this.fill();
        }
        default:
          throw new PumpError("action is switch, float, dose, prime, calibrate or fill", true);
      }
    } catch (err) {
      if (err instanceof SwitchError) throw new PumpError(err.message, true);
      throw err;
    }
  }
  private ready(id: PumpId): Switch {
    if (this.running) throw new PumpError(`the ${this.running} pump is running`, true);
    const sw = this.sw(id);
    if (!sw) throw new PumpError(`the ${id} pump has no switch; wire it first`, true);
    return sw;
  }
  private async dose(id: DosePumpId, ml: unknown): Promise<{ ok: true; ml: number; ms: number }> {
    if (typeof ml !== "number" || !Number.isFinite(ml) || ml <= 0) throw new PumpError("ml is a number above 0", true);
    const sw = this.ready(id);
    const rate = this.s.pumps[id].mlPerSec;
    if (!rate) throw new PumpError(`the ${id} pump is not calibrated; prime it into a measuring cup and enter the ml`, true);
    const ms = Math.round((ml / rate) * 1000);
    if (ms > MAX_RUN_MS) throw new PumpError(`${ml} ml takes ${Math.ceil(ms / 1000)} s, past the Pi's ${MAX_RUN_MS / 1000} s limit for one run`, true);
    if (this.dosedToday(id) + ml > MAX_DAY_ML) throw new PumpError(`past the Pi's daily limit of ${MAX_DAY_ML} ml for the ${id} pump`, true);
    const at = this.now();
    // counted before it runs: a crash mid-dose still counts
    this.s.doses = this.s.doses.filter((d) => d.at > at - 86_400_000).concat({ pump: id, at, ml });
    this.save();
    await this.runFor(id, sw, ms);
    return { ok: true, ml, ms };
  }
  /** On, wait, off; off in every case. A failure after the switch was asked to close is not a refusal. */
  private async runFor(id: PumpId, sw: Switch, ms: number): Promise<void> {
    this.running = id;
    try {
      await sw.on();
      await this.sleep(ms);
    } catch (err) {
      this.error = `${id}: ${(err as Error).message}`;
      throw new PumpError(`the ${id} pump failed: ${(err as Error).message}`, false);
    } finally {
      await this.off(id, sw);
      this.running = null;
    }
  }
  private async off(id: PumpId, sw: Switch): Promise<void> {
    for (let i = 0; i < 3; i++) {
      try {
        await sw.off();
        return;
      } catch (err) {
        this.error = `${id} would not switch off: ${(err as Error).message}`;
        console.error(`dosing: ${this.error}`);
      }
    }
    throw new PumpError(`the ${id} pump would not switch off; cut its power`, false);
  }
  private async fill(): Promise<{ ok: true; stopped: "full" | "cap"; ms: number }> {
    const sw = this.ready("topOff");
    const f = this.floatSwitch();
    if (!f) throw new PumpError("top-off needs a high float to stop on; set its GPIO line first", true);
    this.running = "topOff";
    const start = this.now();
    try {
      const stopped = await topOff({ on: () => sw.on(), off: () => this.off("topOff", sw) }, () => f.state(), { capMs: this.s.capSec * 1000, now: this.now, sleep: this.sleep });
      this.lastFull = stopped === "full" ? true : this.lastFull;
      return { ok: true, stopped, ms: this.now() - start };
    } catch (err) {
      if (err instanceof PumpError) throw err;
      this.error = `topOff: ${(err as Error).message}`;
      throw new PumpError(`top-off failed: ${(err as Error).message}`, false);
    } finally {
      this.running = null;
    }
  }
  private load(): void {
    let raw: unknown;
    try {
      raw = JSON.parse(readFileSync(this.o.file, "utf8"));
    } catch {
      return; // none yet, or unreadable: nothing wired
    }
    if (!isObj(raw)) return;
    // field by field: one bad value must not throw away the rest
    const pumps = isObj(raw.pumps) ? raw.pumps : {};
    for (const id of PUMP_IDS) {
      const p = pumps[id];
      if (!isObj(p)) continue;
      let driver: DriverConfig | null = null;
      try {
        driver = p.driver ? parsePumpDriver(p.driver) : null;
      } catch {
        continue;
      }
      const rate = typeof p.mlPerSec === "number" && p.mlPerSec >= ML_PER_SEC.min && p.mlPerSec <= ML_PER_SEC.max ? p.mlPerSec : null;
      this.s.pumps[id] = { driver, mlPerSec: rate, calibratedAt: rate && typeof p.calibratedAt === "number" ? p.calibratedAt : null };
    }
    try {
      this.s.float = raw.float ? parseFloatLine(raw.float) : null;
    } catch {
      this.s.float = null;
    }
    if (typeof raw.capSec === "number" && Number.isInteger(raw.capSec) && raw.capSec >= TOP_OFF_CAP.min && raw.capSec <= TOP_OFF_CAP.max) this.s.capSec = raw.capSec;
    if (Array.isArray(raw.doses)) this.s.doses = raw.doses.filter((d): d is Stored["doses"][number] => isObj(d) && DOSE_PUMPS.includes(d.pump as DosePumpId) && typeof d.at === "number" && typeof d.ml === "number" && d.ml > 0);
  }
  private save(): void {
    mkdirSync(dirname(this.o.file), { recursive: true });
    writeFileSync(`${this.o.file}.tmp`, JSON.stringify(this.s, null, 1));
    renameSync(`${this.o.file}.tmp`, this.o.file);
  }
}
@@ -0,0 +1,173 @@
import { describe, expect, test } from "bun:test";
import { CareLog, type Reading } from "./care-log.ts";
import { Doser, LOOPS, MIN_WAIT_MS, PumpRefused, topOff, type LoopId } from "./doser.ts";
const T0 = 1_800_000_000_000;
function rig(over: Partial<Record<LoopId, object>> = {}, modes: "auto" | "suggest" = "auto") {
  let t = T0;
  const readings: Record<string, Reading | undefined> = { ph: { kind: "ph", value: 7.2, at: T0, source: "sensor" }, ec: { kind: "ec", value: 1.5, at: T0, source: "sensor" } };
  const ran: Record<string, number[]> = {};
  const pumps = Object.fromEntries(LOOPS.map((l) => [l, { dose: async (ml: number) => void (ran[l] ??= []).push(ml) }])) as never;
  const log = new CareLog(undefined, () => t);
  const loops = Object.fromEntries(LOOPS.map((l) => [l, { mode: modes, ...over[l] }]));
  let cal = true;
  const doser = new Doser({ pumps, latest: (k) => readings[k], calibrated: () => cal, log, loops, now: () => t });
  return {
    doser, ran, log, readings,
    at: (ms: number) => (t = T0 + ms),
    read: (kind: "ph" | "ec", value: number) => (readings[kind] = { kind, value, at: t, source: "sensor" }),
    uncalibrate: () => (cal = false),
  };
}
describe("dose controller", () => {
  test("doses pH down in auto, logs it with its cause", async () => {
    const r = rig();
    const o = await r.doser.dose("phDown", "rule");
    expect(o).toEqual({ ok: true, ml: 4 });
    expect(r.ran.phDown).toEqual([4]);
    const e = r.log.entries()[0]!;
    expect(e).toMatchObject({ type: "action", what: "phdown", amount: 4, cause: "rule" });
  });
  test("refuses beyond the per-dose and the daily limit", async () => {
    const r = rig({ phDown: { maxDoseMl: 5, maxDayMl: 6 } });
    expect(await r.doser.dose("phDown", "crew", 9)).toEqual({ ok: false, reason: "over the per-dose limit of 5 ml" });
    expect(await r.doser.dose("phDown", "crew", 5)).toEqual({ ok: true, ml: 5 });
    r.at(MIN_WAIT_MS + 1);
    r.read("ph", 7.0);
    const o = await r.doser.dose("phDown", "crew", 2);
    expect(o).toEqual({ ok: false, reason: "over the daily limit of 6 ml" });
    expect(r.ran.phDown).toEqual([5]);
  });
  test("no dose on a stale or uncalibrated reading", async () => {
    const r = rig();
    r.at(31 * 60_000);
    expect(await r.doser.dose("phDown", "rule")).toMatchObject({ ok: false, reason: expect.stringContaining("30 minutes") });
    r.read("ph", 7.2);
    r.uncalibrate();
    expect(await r.doser.dose("phDown", "rule")).toMatchObject({ ok: false, reason: expect.stringContaining("not calibrated") });
    expect(r.ran.phDown).toBeUndefined();
  });
  test("never twice on one reading, and not inside the mixing wait", async () => {
    const r = rig();
    await r.doser.dose("phDown", "rule");
    r.at(60_000);
    expect(await r.doser.dose("phDown", "rule")).toMatchObject({ ok: false, reason: expect.stringContaining("mix") });
    r.at(MIN_WAIT_MS + 1); // waited, but no new reading
    expect(await r.doser.dose("phDown", "rule")).toMatchObject({ ok: false });
    expect(r.ran.phDown).toHaveLength(1);
  });
  test("pH down waits for a nutrient dose to mix", async () => {
    const r = rig();
    await r.doser.dose("nutrientA", "rule", 2);
    r.at(120_000);
    expect(await r.doser.dose("phDown", "rule")).toMatchObject({ ok: false, reason: expect.stringContaining("mix") });
  });
  test("a dose that did not move the reading halts automation until the owner resumes", async () => {
    const r = rig();
    await r.doser.dose("phDown", "rule");
    r.at(MIN_WAIT_MS + 1);
    r.read("ph", 7.2); // unchanged
    const o = await r.doser.dose("phDown", "rule");
    expect(o).toMatchObject({ ok: false, reason: expect.stringContaining("did not move ph") });
    expect(r.doser.halted).toContain("did not move");
    r.at(2 * MIN_WAIT_MS);
    r.read("ph", 7.1);
    expect(await r.doser.dose("phDown", "owner")).toMatchObject({ ok: false, reason: expect.stringContaining("stopped") });
    r.doser.resume("owner");
    expect(await r.doser.dose("phDown", "owner")).toMatchObject({ ok: true });
  });
  test("a dose that worked lets the next one through", async () => {
    const r = rig();
    await r.doser.dose("phDown", "rule");
    r.at(MIN_WAIT_MS + 1);
    r.read("ph", 6.9);
    expect(await r.doser.dose("phDown", "rule")).toMatchObject({ ok: true });
  });
  test("a reading outside physical bounds stops automation", async () => {
    const r = rig();
    r.read("ph", 15);
    expect(await r.doser.dose("phDown", "rule")).toMatchObject({ ok: false });
    expect(r.doser.halted).toContain("outside");
    expect(r.ran.phDown).toBeUndefined();
  });
  test("suggest mode never actuates for a rule or the crew; the owner's tap does", async () => {
    const r = rig({}, "suggest");
    expect(r.doser.suggest("phDown")).toMatchObject({ ml: 4, text: "add 4 ml pH down (ph 7.2)" });
    expect(await r.doser.dose("phDown", "rule")).toMatchObject({ ok: false });
    expect(await r.doser.dose("phDown", "crew")).toMatchObject({ ok: false });
    expect(await r.doser.tick()).toEqual({});
    expect(r.ran.phDown).toBeUndefined();
    expect(await r.doser.dose("phDown", "owner")).toEqual({ ok: true, ml: 4 });
  });
  test("off refuses everyone; a reading within the band suggests nothing", async () => {
    const r = rig({ phDown: { mode: "off" } });
    expect(await r.doser.dose("phDown", "owner")).toMatchObject({ ok: false });
    const q = rig();
    q.read("ph", 6.0);
    expect(q.doser.suggest("phDown")).toMatchObject({ reason: expect.stringContaining("within") });
  });
  test("tick doses the loops in auto", async () => {
    const r = rig({ nutrientB: { mode: "off" }, phDown: { mode: "off" } });
    r.read("ec", 1.0);
    const out = await r.doser.tick();
    expect(Object.keys(out)).toEqual(["nutrientA"]);
    expect(out.nutrientA).toMatchObject({ ok: true });
  });
  test("a pump that refuses (nothing ran) is not counted and does not halt", async () => {
    const log = new CareLog(undefined, () => T0);
    let refuse = true;
    const ran: number[] = [];
    const pump = { dose: async (ml: number) => { if (refuse) throw new PumpRefused("the phDown pump is not calibrated"); ran.push(ml); } };
    const ok = { dose: async () => {} };
    const doser = new Doser({ pumps: { nutrientA: ok, nutrientB: ok, phDown: pump }, latest: (k) => (k === "ph" ? { kind: "ph", value: 7.2, at: T0, source: "sensor" } : undefined), calibrated: () => true, log, loops: { phDown: { mode: "auto" } }, now: () => T0 });
    expect(await doser.dose("phDown", "rule")).toEqual({ ok: false, reason: "the phDown pump is not calibrated" });
    expect(doser.halted).toBeNull();
    expect(doser.dosedToday("phDown")).toBe(0);
    expect(log.entries()).toHaveLength(0);
    refuse = false;
    // no mixing wait and the same reading still usable: nothing was dosed
    expect(await doser.dose("phDown", "rule")).toEqual({ ok: true, ml: 4 });
    expect(ran).toEqual([4]);
  });
  test("a config with the per-dose limit above the daily one is refused", () => {
    expect(() => rig({ phDown: { maxDoseMl: 50, maxDayMl: 10 } })).toThrow("daily limit");
  });
});
describe("top-off", () => {
  const fake = () => {
    let t = 0;
    const calls: string[] = [];
    return { calls, now: () => t, sleep: async (ms: number) => void (t += ms), pump: { on: async () => void calls.push("on"), off: async () => void calls.push("off") } };
  };
  test("stops at the high float", async () => {
    const f = fake();
    let polls = 0;
    expect(await topOff(f.pump, async () => ++polls > 3, { capMs: 60_000, now: f.now, sleep: f.sleep })).toBe("full");
    expect(f.calls).toEqual(["on", "off"]);
    expect(f.now()).toBeLessThan(5000);
  });
  test("stops at the time cap when the float never trips", async () => {
    const f = fake();
    expect(await topOff(f.pump, async () => false, { capMs: 10_000, now: f.now, sleep: f.sleep })).toBe("cap");
    expect(f.calls).toEqual(["on", "off"]);
  });
  test("does not start when already full", async () => {
    const f = fake();
    expect(await topOff(f.pump, async () => true, { capMs: 10_000, now: f.now, sleep: f.sleep })).toBe("full");
    expect(f.calls).toEqual([]);
  });
});
@@ -0,0 +1,337 @@
/**
 * The dose controller: sensors measure, pumps act, and this module decides inside limits that live here, on the Pi,
 * never in the agent that asks. One loop per pump (nutrient A, nutrient B, pH down), each `off`, `suggest` or `auto`.
 *   - a dose is refused over its per-dose or per-day ml, on a stale (>30 min) or uncalibrated reading, on a reading it
 *     already dosed on, and inside the mixing wait (≥10 min) after any dose;
 *   - after the wait the next reading must have moved the way the dose should move it; if not, or if a reading is
 *     outside physical bounds, automation halts until the owner resumes it;
 *   - `suggest` never actuates for a rule or a crew agent: only the owner's tap does;
 *   - every dose is written to the log book with its cause.
 * Pumps, readings and the clock are injected, so the tests use fakes. Top-off is `topOff` below; the Pi runs it.
 */
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";
import type { Cause, CareLog, Reading } from "./care-log.ts";
import type { Measure } from "./care-profile.ts";
export const LOOPS = ["nutrientA", "nutrientB", "phDown"] as const;
export type LoopId = (typeof LOOPS)[number];
export const MODES = ["off", "suggest", "auto"] as const;
export type Mode = (typeof MODES)[number];
export const STALE_MS = 30 * 60_000;
export const MIN_WAIT_MS = 10 * 60_000;
/**
 * A dosing pump: pumps ml, turning them into run time with its own measured ml/s (src/dose-pumps.ts on the Pi).
 * It throws PumpRefused when it ran nothing (no switch, no calibration, its own backstop); anything else it throws
 * means it may have run.
 */
export interface Pump {
  /** A stand-in with nothing wired: the log book says so instead of claiming water was dosed. */
  simulated?: boolean;
  dose(ml: number): Promise<void>;
}
/** The pump ran nothing: the dose is not counted and automation carries on. */
export class PumpRefused extends Error {}
export interface LoopConfig {
  mode: Mode;
  maxDoseMl: number;
  maxDayMl: number;
  /** The reading it answers, the band's edge that triggers it, and how many ml move the reading by one unit (conservative). */
  kind: Measure;
  trigger: "above" | "below";
  target: number;
  mlPerUnit: number;
  /** The smallest move after a dose that counts as the pump having worked. */
  minMove: number;
}
export const DEFAULTS: Record<LoopId, LoopConfig> = {
  nutrientA: { mode: "suggest", maxDoseMl: 10, maxDayMl: 40, kind: "ec", trigger: "below", target: 1.2, mlPerUnit: 20, minMove: 0.02 },
  nutrientB: { mode: "suggest", maxDoseMl: 10, maxDayMl: 40, kind: "ec", trigger: "below", target: 1.2, mlPerUnit: 20, minMove: 0.02 },
  phDown: { mode: "suggest", maxDoseMl: 5, maxDayMl: 15, kind: "ph", trigger: "above", target: 6.2, mlPerUnit: 4, minMove: 0.05 },
};
/** Physical bounds: a reading outside them is a broken probe, not water. */
export const BOUNDS: Partial<Record<Measure, [number, number]>> = { ph: [2, 12], ec: [0, 6], waterTemp: [2, 40] };
const LABEL: Record<LoopId, string> = { nutrientA: "nutrient A", nutrientB: "nutrient B", phDown: "pH down" };
const ACTION: Record<LoopId, "nutrients" | "phdown"> = { nutrientA: "nutrients", nutrientB: "nutrients", phDown: "phdown" };
export type Outcome = { ok: true; ml: number } | { ok: false; reason: string };
export type Suggestion = { ml: number; text: string } | { reason: string };
interface Saved {
  halted: string | null;
  lastDoseAt: number;
  /** Per loop: the reading time last dosed on. */
  usedReading: Partial<Record<LoopId, number>>;
  /** What to check once the wait is over. */
  pending: { loop: LoopId; kind: Measure; before: number; at: number; expect: "down" | "up"; minMove: number } | null;
  /** Doses in the last day, for the daily limit. */
  doses: { loop: LoopId; at: number; ml: number }[];
  /** The owner's choice per loop; a loop not here is at its configured mode. */
  modes: Partial<Record<LoopId, Mode>>;
}
const num = (v: unknown) => typeof v === "number" && Number.isFinite(v);
const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
/** Whether a parsed file has the shape Saved promises; anything else is not trusted. */
function savedOk(v: unknown): v is Saved {
  if (!isObj(v)) return false;
  const p = v.pending;
  return (
    (v.halted === null || typeof v.halted === "string") &&
    num(v.lastDoseAt) &&
    isObj(v.usedReading) && Object.values(v.usedReading).every(num) &&
    (p === null || (isObj(p) && LOOPS.includes(p.loop as LoopId) && num(p.before) && num(p.at) && num(p.minMove) && (p.expect === "down" || p.expect === "up") && typeof p.kind === "string")) &&
    Array.isArray(v.doses) && v.doses.every((x) => isObj(x) && LOOPS.includes(x.loop as LoopId) && num(x.at) && num(x.ml)) &&
    isObj(v.modes) && Object.entries(v.modes).every(([k, m]) => LOOPS.includes(k as LoopId) && MODES.includes(m as Mode))
  );
}
export interface DoserDeps {
  pumps: Record<LoopId, Pump>;
  /** The newest reading of a kind, or undefined. */
  latest: (kind: Measure) => Reading | undefined;
  /** Whether the probe behind a kind is calibrated (manual entries count as calibrated). */
  calibrated: (kind: Measure) => boolean;
  log: CareLog;
  loops?: Partial<Record<LoopId, Partial<LoopConfig>>>;
  file?: string;
  now?: () => number;
}
export class Doser {
  readonly loops: Record<LoopId, LoopConfig>;
  private s: Saved = { halted: null, lastDoseAt: 0, usedReading: {}, pending: null, doses: [], modes: {} };
  private busy = false;
  private readonly d: DoserDeps;
  constructor(deps: DoserDeps) {
    this.d = deps;
    this.loops = Object.fromEntries(LOOPS.map((l) => [l, { ...DEFAULTS[l], ...deps.loops?.[l] }])) as Record<LoopId, LoopConfig>;
    for (const l of LOOPS) validate(l, this.loops[l]);
    if (deps.file && existsSync(deps.file)) {
      try {
        const saved: unknown = JSON.parse(readFileSync(deps.file, "utf8"));
        if (!savedOk(saved)) throw new Error("unexpected shape");
        this.s = saved;
        for (const l of LOOPS) if (saved.modes[l]) this.loops[l].mode = saved.modes[l]!;
      } catch {
        // an unreadable file means we don't know what was dosed: stay stopped
        this.s.halted = "the dosing record was unreadable; check the reservoir, then resume";
      }
    }
  }
  private now() {
    return this.d.now?.() ?? Date.now();
  }
  private save() {
    if (!this.d.file) return;
    mkdirSync(dirname(this.d.file), { recursive: true });
    writeFileSync(`${this.d.file}.tmp`, JSON.stringify(this.s));
    renameSync(`${this.d.file}.tmp`, this.d.file);
  }
  get halted(): string | null {
    return this.s.halted;
  }
  /** The owner's say-so that the reservoir is as it should be. Only the owner: a rule or an agent cannot lift its own stop. */
  resume(cause: Cause) {
    if (cause !== "owner") throw new Error("only the owner may resume dosing");
    this.s.halted = null;
    this.s.pending = null;
    this.save();
  }
  /** Only the owner changes a mode, and it is kept across a restart. */
  setMode(loop: LoopId, mode: Mode, cause: Cause) {
    if (cause !== "owner") throw new Error("only the owner may change a mode");
    if (!LOOPS.includes(loop)) throw new Error(`loop is one of ${LOOPS.join(", ")}`);
    if (!MODES.includes(mode)) throw new Error(`mode is one of ${MODES.join(", ")}`);
    this.loops[loop].mode = mode;
    this.s.modes[loop] = mode;
    this.save();
  }
  /** What a page or the terminal shows: per loop its mode, what it would add and what it has used today. */
  status() {
    return {
      halted: this.s.halted,
      simulated: LOOPS.some((l) => this.d.pumps[l].simulated),
      loops: LOOPS.map((l) => {
        const c = this.loops[l];
        const sg = this.suggest(l);
        return { id: l, label: LABEL[l], mode: c.mode, suggestion: "ml" in sg ? sg : null, reason: "reason" in sg ? sg.reason : null, dosedTodayMl: this.dosedToday(l), maxDoseMl: c.maxDoseMl, maxDayMl: c.maxDayMl };
      }),
    };
  }
  /** ml dosed by a loop in the last 24 h. */
  dosedToday(loop: LoopId): number {
    const since = this.now() - 86_400_000;
    return this.s.doses.filter((x) => x.loop === loop && x.at > since).reduce((n, x) => n + x.ml, 0);
  }
  private halt(reason: string): never[] {
    this.s.halted = reason;
    this.s.pending = null;
    this.save();
    return [];
  }
  /**
   * The reading a dose would act on, or why there is none. A reading outside physical bounds, or a dose that did nothing,
   * stops automation; that and clearing a passed check happen only with `act` (a dose), never on a read.
   */
  private usable(loop: LoopId, act: boolean): Reading | string {
    const c = this.loops[loop];
    const r = this.d.latest(c.kind);
    if (!r) return `no ${c.kind} reading`;
    const bounds = BOUNDS[c.kind];
    if (bounds && (r.value < bounds[0] || r.value > bounds[1])) {
      const why = `${c.kind} ${r.value} is outside what water can read; check the probe`;
      if (act) this.halt(why);
      return `stopped: ${why}`;
    }
    const now = this.now();
    if (now - r.at > STALE_MS) return `the ${c.kind} reading is more than 30 minutes old`;
    if (!this.d.calibrated(c.kind)) return `the ${c.kind} probe is not calibrated`;
    const p = this.s.pending;
    if (p) {
      if (now - p.at < MIN_WAIT_MS || r.at < p.at + MIN_WAIT_MS) return "waiting for the dose to mix, then a fresh reading";
      const moved = p.expect === "down" ? p.before - r.value : r.value - p.before;
      if (moved < p.minMove) {
        const why = `the last ${p.loop} dose did not move ${p.kind} as expected (${p.before} → ${r.value}); check the pump and the probe`;
        if (act) this.halt(why);
        return `stopped: ${why}`;
      }
      if (act) {
        this.s.pending = null;
        this.save();
      }
    }
    if (r.at <= (this.s.usedReading[loop] ?? 0)) return "already dosed on this reading; waiting for a new one";
    return r;
  }
  /** What the loop would add now, or why not. Never actuates. */
  suggest(loop: LoopId): Suggestion {
    const c = this.loops[loop];
    if (this.s.halted) return { reason: `stopped: ${this.s.halted}` };
    if (c.mode === "off") return { reason: "this loop is off" };
    const r = this.usable(loop, false);
    if (typeof r === "string") return { reason: r };
    const gap = c.trigger === "above" ? r.value - c.target : c.target - r.value;
    if (gap <= 0) return { reason: `${c.kind} ${r.value} is within its band` };
    const ml = Math.min(round(gap * c.mlPerUnit), c.maxDoseMl, Math.max(0, c.maxDayMl - this.dosedToday(loop)));
    if (ml < 0.5) return { reason: "the daily limit is reached" };
    return { ml, text: `add ${ml} ml ${LABEL[loop]} (${c.kind} ${r.value})` };
  }
  /**
   * Run a dose. `rule` and `crew` need the loop in auto; the owner may also act in suggest. Every limit applies to all three.
   * With no `ml`, the suggested amount.
   */
  async dose(loop: LoopId, cause: Cause, ml?: number): Promise<Outcome> {
    const c = this.loops[loop];
    if (this.busy) return refuse("a dose is running");
    if (this.s.halted) return refuse(`stopped: ${this.s.halted}`);
    if (c.mode === "off") return refuse("this loop is off");
    if (c.mode === "suggest" && cause !== "owner") return refuse("this loop only suggests; the owner taps Do it");
    const wait = this.now() - this.s.lastDoseAt;
    if (wait < MIN_WAIT_MS) return refuse(`wait ${Math.ceil((MIN_WAIT_MS - wait) / 60_000)} more minutes for the last dose to mix`);
    const r = this.usable(loop, true);
    if (typeof r === "string") return refuse(r);
    if (ml === undefined) {
      const s = this.suggest(loop);
      if ("reason" in s) return refuse(s.reason);
      ml = s.ml;
    }
    if (!(typeof ml === "number" && Number.isFinite(ml) && ml > 0)) return refuse("ml is a number above 0");
    if (ml > c.maxDoseMl) return refuse(`over the per-dose limit of ${c.maxDoseMl} ml`);
    if (this.dosedToday(loop) + ml > c.maxDayMl) return refuse(`over the daily limit of ${c.maxDayMl} ml`);
    const at = this.now();
    const before = { lastDoseAt: this.s.lastDoseAt, used: this.s.usedReading[loop], doses: this.s.doses, pending: this.s.pending };
    this.busy = true;
    try {
      this.s.lastDoseAt = at;
      this.s.usedReading[loop] = r.at;
      this.s.doses = this.s.doses.filter((x) => x.at > at - 86_400_000).concat({ loop, at, ml });
      this.s.pending = { loop, kind: c.kind, before: r.value, at, expect: c.trigger === "above" ? "down" : "up", minMove: c.minMove };
      this.save(); // before the pump runs: a crash mid-dose still counts against the limits
      try {
        await this.d.pumps[loop].dose(ml);
      } catch (err) {
        if (err instanceof PumpRefused) {
          // nothing ran: put the record back as it was
          this.s.lastDoseAt = before.lastDoseAt;
          if (before.used === undefined) delete this.s.usedReading[loop];
          else this.s.usedReading[loop] = before.used;
          this.s.doses = before.doses;
          this.s.pending = before.pending;
          this.save();
          return refuse(err.message);
        }
        // the ml stay counted (we cannot know how much ran); say so and stop
        const why = `the ${loop} pump failed (${(err as Error).message}); check the reservoir, then resume`;
        this.halt(why);
        this.d.log.add({ type: "observation", text: `Dosing stopped: ${why}` });
        return refuse(`stopped: ${why}`);
      }
      if (this.d.pumps[loop].simulated) this.d.log.add({ type: "observation", text: `Simulated dose, nothing was pumped: ${ml} ml ${LABEL[loop]} (${cause})` });
      else this.d.log.add({ type: "action", what: ACTION[loop], amount: ml, cause });
    } finally {
      this.busy = false;
    }
    return { ok: true, ml };
  }
  /** One pass of automation: dose each loop that is in auto and has something to add. Returns what it did. */
  async tick(): Promise<Record<string, Outcome>> {
    const out: Record<string, Outcome> = {};
    for (const l of LOOPS) {
      if (this.loops[l].mode !== "auto") continue;
      const s = this.suggest(l);
      if ("ml" in s) out[l] = await this.dose(l, "rule", s.ml);
    }
    return out;
  }
}
const refuse = (reason: string): Outcome => ({ ok: false, reason });
const round = (n: number) => Math.round(n * 10) / 10;
function validate(id: LoopId, c: LoopConfig) {
  if (!MODES.includes(c.mode)) throw new Error(`${id}: mode is one of ${MODES.join(", ")}`);
  for (const k of ["maxDoseMl", "maxDayMl", "mlPerUnit", "minMove"] as const) {
    if (!(typeof c[k] === "number" && Number.isFinite(c[k]) && c[k] > 0)) throw new Error(`${id}: ${k} is a number above 0`);
  }
  if (c.maxDoseMl > c.maxDayMl) throw new Error(`${id}: the per-dose limit is above the daily limit`);
}
/**
 * Top-off: run the fresh-water pump until the high float says full or the time cap passes, whichever comes first.
 * `full` is polled every `pollMs`; the pump is stopped in all cases, including a throw.
 */
export async function topOff(pump: { on(): Promise<void>; off(): Promise<void> }, full: () => Promise<boolean>, opts: { capMs: number; pollMs?: number; now?: () => number; sleep?: (ms: number) => Promise<void> }): Promise<"full" | "cap"> {
  const now = opts.now ?? Date.now;
  const sleep = opts.sleep ?? ((ms) => new Promise<void>((r) => setTimeout(r, ms)));
  if (await full()) return "full";
  const end = now() + opts.capMs;
  try {
    await pump.on();
    while (now() < end) {
      await sleep(opts.pollMs ?? 500);
      if (await full()) return "full";
    }
    return "cap";
  } finally {
    await pump.off();
  }
}
@@ -0,0 +1,61 @@
/**
 * The pumps on the /care dosing card, the owner's only: each pump's switch, its measured ml/s and today's ml, and the
 * steps to set one up — wire it (a GPIO relay or MOSFET line, or a Shelly plug), prime it for 10 s into a measuring
 * cup, type the ml the cup caught — then the top-off pump with its high float and time cap. Plain forms to
 * /care/dosing/pump, no script; the Pi checks every field (src/dose-pumps.ts). Everything shown is escaped.
 */
import { PUMP_LABEL } from "./arm-pumps.ts";
import { PUMP_IDS, type DosingView, type PumpId, type PumpView } from "./dose-pumps.ts";
import { esc } from "./story-markdown.ts";
const ACTION = "/care/dosing/pump";
const PRIME_SEC = 10;
const hidden = (fields: Record<string, string>) => Object.entries(fields).map(([k, v]) => `<input type="hidden" name="${esc(k)}" value="${esc(v)}">`).join("");
const form = (fields: Record<string, string>, inner: string, label: string, cls = "") => `<form method="post" action="${ACTION}">${hidden(fields)}${inner}<button${cls ? ` class="${cls}"` : ""}>${esc(label)}</button></form>`;
const day = (at: number) => new Date(at).toISOString().slice(0, 10);
function wiring(p: PumpView): string {
  const fields = { action: "switch", pump: p.id };
  return `<details${p.driver ? "" : " open"}><summary>Wire ${esc(PUMP_LABEL[p.id])}${p.driver ? ` · ${esc(p.driver)}` : ""}</summary>
${form({ ...fields, driver: "gpio" }, `<label>GPIO line <input name="line" type="number" required min="0" max="63" step="1" inputmode="numeric" placeholder="17"></label><label><input name="activeLow" type="checkbox" style="min-height:auto"> closes on 0</label>`, "Use relay / MOSFET", "quiet")}
${form({ ...fields, driver: "shelly" }, `<label>Shelly plug <input name="host" required maxlength="80" class="wide" autocapitalize="none" autocomplete="off" spellcheck="false" placeholder="192.168.1.40"></label>`, "Use plug", "quiet")}
${p.driver ? form({ ...fields, driver: "none" }, "", "Unwire", "quiet") : ""}
<p class="dim">A new switch clears the calibration: prime and measure again.</p></details>`;
}
function calibration(p: PumpView, primed: DosingView["primed"]): string {
  if (!p.driver) return "";
  const prime = form({ action: "prime", pump: p.id, sec: String(PRIME_SEC) }, "", p.mlPerSec ? `Prime ${PRIME_SEC} s` : `1. Run ${PRIME_SEC} s into a measuring cup`, p.mlPerSec ? "quiet" : "");
  const caught = primed?.pump === p.id
    ? form({ action: "calibrate", pump: p.id }, `<label>2. The cup caught <input name="ml" type="number" required min="0.1" max="1000" step="0.1" inputmode="decimal"> ml in ${primed.ms / 1000} s</label>`, "Save calibration")
    : "";
  return `${prime}${caught}`;
}
function row(p: PumpView, v: DosingView): string {
  const cal = p.mlPerSec ? `${p.mlPerSec} ml/s, measured ${p.calibratedAt ? day(p.calibratedAt) : "earlier"}` : p.driver ? "not calibrated: it will not dose" : "not wired";
  const today = p.id === "topOff" ? "" : ` · today ${p.dosedTodayMl} of the Pi's ${v.maxDayMl} ml`;
  return `<li data-pump="${esc(p.id)}"><span><strong>${esc(PUMP_LABEL[p.id])}</strong>${v.running === p.id ? " · running" : ""}<br><span class="dim">${esc(cal)}${today}</span></span>
<span>${calibration(p, v.primed)}</span>${wiring(p)}</li>`;
}
function topOff(v: DosingView): string {
  const p = v.pumps.find((x) => x.id === "topOff");
  const float = v.float ? `high float on GPIO ${v.float.line}${v.float.activeLow ? " (closes on 0)" : ""}: ${v.full === null ? "no answer" : v.full ? "full" : "not full"}` : "no high float set: top-off will not run";
  const go = p?.driver && v.float ? form({ action: "fill" }, "", "Top off now") : "";
  return `<li data-pump="topOff-fill"><span><strong>Fill</strong><br><span class="dim">${esc(float)} · stops at ${v.capSec} s at most</span></span><span>${go}</span>
<details${v.float ? "" : " open"}><summary>Float and time cap</summary>
${form({ action: "float" }, `<label>Float GPIO line <input name="line" type="number" min="0" max="63" step="1" inputmode="numeric" value="${v.float ? v.float.line : ""}" placeholder="27"></label><label><input name="activeLow" type="checkbox" style="min-height:auto"${v.float?.activeLow ? " checked" : ""}> closes on 0</label><label>Cap <input name="capSec" type="number" min="5" max="600" step="1" inputmode="numeric" value="${v.capSec}"> s</label>`, "Save", "quiet")}
<p class="dim">Leave the line empty to remove the float.</p></details></li>`;
}
/** The pumps section; null is the Pi not answering. */
export function renderPumps(v: DosingView | null): string {
  if (!v) return `<h3>Pumps</h3><p class="dim">The arm server did not answer, so the pumps cannot be read or set up. Nothing doses until it does.</p>`;
  const pumps = PUMP_IDS.map((id: PumpId) => v.pumps.find((p) => p.id === id)).filter((p): p is PumpView => !!p);
  return `<h3>Pumps</h3>
${v.error ? `<p class="alert" role="alert">The Pi says: ${esc(v.error)}</p>` : ""}
<p class="dim">Each pump stops after ${v.maxRunMs / 1000} s and ${v.maxDayMl} ml a day whatever is asked: that backstop is on the Pi.</p>
<ul class="list">${pumps.map((p) => row(p, v)).join("")}${topOff(v)}</ul>`;
}
@@ -110,6 +110,9 @@
import { CareLog } from "./care-log.ts";
import { BUILT_IN_DIR, loadProfiles, type Profile } from "./care-profile.ts";
import { ProbeCache, readProbeView, sampleProbes, waterTemp, type ProbeHooks } from "./care-probes.ts";
import { handleCare } from "./care-routes.ts";
import { handleDosing, makeDoser } from "./care-dosing.ts";
import type { Doser } from "./doser.ts";
import { armPumps, cachedRead, readDosing, type PumpHooks } from "./arm-pumps.ts";
import { renderWorkshop, type StationView } from "./workshop-page.ts";
import { DAY_MS, GrowStills, KEEP_DAYS } from "./grow-stills.ts";
import { finishStillApart } from "./grow-frame.ts";
@@ -164,7 +167,7 @@
export interface RelayOptions {
  /** The workshop's stations; by default in memory, the arm alone. */
  stations?: StationHub;
  /** The plant care app's log book and plant profile (src/care-routes.ts); by default in memory, with the built-in spinach profile. */
  care?: { log: CareLog; profile: Profile };
  care?: { log: CareLog; profile: Profile; doser?: Doser; dosingFile?: string };
  /** How often the Pi's pH/EC probes are read into the care log, ms; unset, they are not sampled (the page still shows them and walks the calibration). */
  probeEveryMs?: number;
  /** The grow box's stills, log and how often a still is taken (src/grow-stills.ts); without it nothing is taken and the card shows no timelapse. */
@@ -330,6 +333,9 @@
export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
  const metrics = new LiveMetrics();
  const stations = options.stations ?? new StationHub(undefined, ARM_ONLY);
  const care = options.care ?? { log: new CareLog(), profile: loadProfiles(BUILT_IN_DIR).find((p) => p.id === "spinach")! };
  /** The Pi's dosing pumps (src/dose-pumps.ts), reached through the arm server like the grow light; set up below with armGrow. */
  const pumpHooks: PumpHooks = { read: () => pumpRead.read(), write: (body, timeoutMs) => pumpWrite(body, timeoutMs) };
  const doser = care.doser ?? makeDoser(care.log, armPumps(pumpHooks), care.dosingFile);
  const cameras = options.cameras ?? new CameraHub({ feed: { ...options.camera, metrics }, seed: remote ? [{ name: "Camera 1", source: remote.cameras[0]! }] : [] });
  const leaders = options.leaders ?? new LeaderCalibrations();
  const videos = new Map<number, VideoFeed>(Object.entries(options.video ?? {}).map(([id, sources]) => [Number(id), new VideoFeed(sources, {}, options.env ?? process.env)]));
@@ -658,6 +664,27 @@
export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
      }
    },
  };
  const pumpRead = cachedRead(async () => {
    try {
      const answer = await fetch(armGrow("/dosing"), { cache: "no-store", signal: AbortSignal.timeout(Math.min(readTimeoutMs, 1000)) });
      return answer.ok ? readDosing(await answer.json().catch(() => null)) : null;
    } catch {
      return null;
    }
  });
  /** One request to the Pi's pumps; the relay's own, never a browser's (a browser's /grow/dosing is refused below). */
  const pumpWrite = async (body: Record<string, unknown>, timeoutMs: number): Promise<import("./arm-pumps.ts").PumpAnswer> => {
    try {
      const answer = await fetch(armGrow("/dosing"), { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs) });
      const parsed = (await answer.json().catch(() => null)) as { error?: unknown } | null;
      if (answer.ok) return { ok: true, body: parsed };
      return { ok: false, status: answer.status, error: typeof parsed?.error === "string" ? parsed.error.replace(/[\p{Cc}\p{Cf}]/gu, "").slice(0, 300) : `the arm server answered ${answer.status}` };
    } catch (err) {
      return { ok: false, status: 0, error: `the arm server did not answer (${reason(err)})` };
    } finally {
      void pumpRead.refresh().catch(() => {});
    }
  };
  /** The arm's servo registers for the owner's admin page; null when the arm does not answer in time. */
  const askServos = async () => {
    try {
@@ -1122,9 +1149,10 @@
export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
      if (/^\/care(?:\/|$)/.test(url.pathname)) {
        const who = (r: IncomingMessage) => {
          const person = lobby ? lobby.who(r) : LOCAL_PERSON;
          return { owner: Boolean(person?.owner), known: Boolean(person), signedIn: lobby && !lobby.local ? lobby.signedIn(r) : null };
          return { owner: Boolean(person?.owner), known: Boolean(person), id: person?.id, signedIn: lobby && !lobby.local ? lobby.signedIn(r) : null };
        };
        if (await handleCare(req, res, url.pathname, { ...care, probes: probeCache, who, readBody })) return;
        if (await handleDosing(req, res, url.pathname, { doser, log: care.log, who, readBody, sameOrigin, pumps: pumpHooks })) return;
        if (await handleCare(req, res, url.pathname, { profile: care.profile, log: care.log, probes: probeCache, doser, pumps: () => pumpRead.read(), who, readBody })) return;
      }
      if (reading && url.pathname === "/stations") return json(res, 200, stationViews().map(({ station, present, resting, cameras: c }) => ({ id: station.id, name: station.name, kind: station.kind, present, ...(resting ? { resting } : {}), cameras: c })));
      const cameraAdmin = ADMIN_CAMERA.exec(url.pathname);
@@ -1157,6 +1185,8 @@
export async function startRelay(options: RelayOptions): Promise<RunningRelay> {
        res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
        return res.end(text);
      }
      // The Pi's pumps answer the relay's controller alone: a browser that reached them would skip every dosing limit.
      if (url.pathname === "/grow/dosing" || url.pathname.startsWith("/grow/dosing/")) return json(res, 404, { error: "not found" });
      if (url.pathname.startsWith("/grow/") && options.grow) {
        const handled = await growRoutes(req, res, url);
        if (handled) return;
@@ -54,6 +54,9 @@
 *   GET  /probes            the pH and EC probes on the ADS1115 (src/probes.ts): values (null until calibrated), ?temp= compensates, and the next calibration step
 *   POST /probes/calibrate  {"step": "ph7"|"ph4"|"ec1413", "tempC"?: number}; 400 says what to do
 *   POST /grow/pump         the same, with an interval schedule {"onMinutes": 5, "offMinutes": 25}
 *   GET  /grow/dosing       the dosing pumps (src/dose-pumps.ts): each one's switch, ml/s and when it was calibrated, the high float, today's ml
 *   POST /grow/dosing       {"action": "switch"|"float"|"dose"|"prime"|"calibrate"|"fill", "pump"?, ...}; 409 is refused before anything ran,
 *                           500 a pump that failed once switched on. The relay alone asks: its controller (src/doser.ts) holds the limits
 *   GET  /tuning            the run's phase while one is under way, and the last outcome
 *   GET  /precision/trace?session=<id>   a kept session's 5 Hz intent and read-back per joint, ticks: {session, t0, hz, joints} (400 bad id, 404 unknown or evicted; the last 20 sessions)
 *   POST /precision/snap-back   {"cause": one of CAUSES, "sizeDeg"}: a snap-back only the page saw, counted beside the server's own (400 for any other cause)
@@ -108,6 +111,7 @@
import { CalError } from "./probe-math.ts";
import { Probes } from "./probes.ts";
import { loadSensors, Sensors } from "./sensors.ts";
import { DEVICES, Light, LightError, type DeviceName } from "./light.ts";
import { DosePumps, PumpError } from "./dose-pumps.ts";
import { ARRIVE_TICKS, LINK_HOPS, parseSnapBack, READ_BACK_HOP, RELAY_HOP, type Cause, type Tracker } from "./precision.ts";
import { deployedCommit, PrecisionHistory, TRACE_HZ } from "./precision-history.ts";
import { Tuning, TuningRefused } from "./tuning.ts";
@@ -146,6 +150,8 @@
export interface ServerOptions {
  lightMs?: number;
  /** The grow light and the pump, for tests that give them a fake switch. */
  lights?: Record<DeviceName, Light>;
  /** The dosing pumps, for tests that give them fake switches. */
  dosePumps?: DosePumps;
  /** The pH/EC probes on the ADS1115, for tests that give them a fake ADC. */
  probes?: Probes;
  /** How often the sensors (src/sensors.ts, listed in sensors.json) are read, ms; unset, they are not run. */
@@ -254,6 +260,7 @@
export async function startServer(bus: FeetechBus, options: ServerOptions = {}):
  }
  const metrics = new Metrics(join(dataDir, "metrics.jsonl"));
  const lights = options.lights ?? { light: new Light({ name: "light", file: join(dataDir, "light.json") }), pump: new Light({ name: "pump", file: join(dataDir, "pump.json") }) };
  const dosePumps = options.dosePumps ?? new DosePumps({ file: join(dataDir, "dose-pumps.json") });
  const probes = options.probes ?? new Probes(ads1115(), join(dataDir, "probes.json"));
  const sensors = options.sensors ?? loadSensors(join(dataDir, "sensors.json"));
  const precision = new PrecisionHistory({ file: join(dataDir, "precision.sqlite"), commit: options.commit });
@@ -996,6 +1003,15 @@
export async function startServer(bus: FeetechBus, options: ServerOptions = {}):
          }
          return json(res, 200, device.view());
        }
        case "GET /grow/dosing":
          return json(res, 200, await dosePumps.view());
        case "POST /grow/dosing":
          try {
            return json(res, 200, await dosePumps.act(await readBody(req)));
          } catch (err) {
            if (err instanceof PumpError) throw new HttpError(err.refused ? 409 : 500, err.message);
            throw err;
          }
        case "GET /probes": {
          const t = url.searchParams.get("temp");
          return json(res, 200, await probes.view(t !== null && /^\d{1,2}(\.\d{1,3})?$/.test(t) ? Number(t) : undefined));
@@ -1812,6 +1828,7 @@
export async function startServer(bus: FeetechBus, options: ServerOptions = {}):
  if (gainTimer) void gainSync.tick();
  const lightTimer = options.lightMs ? setInterval(() => DEVICES.forEach((d) => void lights[d].tick()), options.lightMs) : undefined;
  if (options.lightMs) DEVICES.forEach((d) => void lights[d].boot());
  void dosePumps.boot();
  const sensorTimer = options.sensorsMs ? setInterval(() => void sensors.tick(), options.sensorsMs) : undefined;
  if (options.sensorsMs) void sensors.tick();
  const address = http.address();
@@ -74,7 +74,7 @@
import { readTuning, tuningSentence, type TuningView } from "./tuning-panel.ts";
import { JOINTS } from "./sts3215.ts";
import { headlineValue, hopLines, NO_HOPS, P95_RULE, readPrecision, sampleSize, sparkline, type PrecisionPanel } from "./precision-panel.ts";
import { probeLines } from "./care-probes.ts";
import { careCommand, careLines, probesCommand, type CareAsk } from "./care-terminal.ts";
import { careCommand, careLines, dosingLines, pumpLines, pumpSaid, probesCommand, type CareAsk } from "./care-terminal.ts";
import { presenceText } from "./ui/lobby-panel.js";
import { entryLine, jointRows, linkRows, stateRows } from "./ui/machine.js";
@@ -192,10 +192,12 @@
export function careReader(env: Env, fetcher: typeof fetch = fetch): ReadCare {
  return async (ask) => {
    try {
      const write = ask.method !== "GET";
      const r = await fetcher(`${appUrl(env)}${ask.path}`, { method: ask.method, headers: { ...terminalHeaders(env), ...(write ? { "content-type": "application/json" } : {}) }, ...(write ? { body: JSON.stringify(ask.body ?? {}) } : {}), signal: AbortSignal.timeout(5000) });
      const r = await fetcher(`${appUrl(env)}${ask.path}`, { method: ask.method, headers: { ...terminalHeaders(env), ...(write ? { "content-type": "application/json" } : {}) }, ...(write ? { body: JSON.stringify(ask.body ?? {}) } : {}), signal: AbortSignal.timeout(ask.timeoutMs ?? 5000) });
      const body = (await r.json().catch(() => null)) as unknown;
      if (!r.ok) return { error: plain((body as { error?: unknown } | null)?.error ?? `status ${r.status}`), lines: [] };
      return { error: null, lines: ask.path === "/care/probes/calibrate" ? ["probe captured", ...probeLines({ view: body }).map(plain)] : write ? ["care saved"] : ask.path === "/care/probes" ? probeLines(body).map(plain) : careLines(body).map(plain) };
      if (ask.path === "/care/probes/calibrate") return { error: null, lines: ["probe captured", ...probeLines({ view: body }).map(plain)] };
      if (write) return { error: null, lines: [plain(ask.path === "/care/dosing/pump" ? pumpSaid(body) : ask.path.startsWith("/care/dosing") ? "dosing: done" : "care saved")] };
      return { error: null, lines: (ask.path === "/care/dosing" ? dosingLines(body) : ask.path === "/care/probes" ? probeLines(body) : ask.path === "/care/dosing/pumps" ? pumpLines(body) : careLines(body)).map(plain) };
    } catch (err) {
      return { error: plain((err as Error).message), lines: [] };
    }
		@@ -265,3 +265,34 @@ Not drawn yet, because nothing records it: latency per hop (page → relay → P
265	265	## Faster limits
266	266
267	267	A person runs this at the arm while nobody drives: `bun bench/limits-search.ts http://<arm>:8101` (add `--joint 2` for one joint; with no URL it runs on the fake bus). From today's 90 °/s and 360 °/s² it steps each joint's speed and acceleration up within the safety ranges (the gripper is skipped), sweeps at each step, and keeps the last step that did not make p95 error or overshoot worse, writing them through `PUT /settings`. It prints its command line, then a table of limits and p95 error, overshoot and time to arrive, before → after. It refuses to start while anyone drives or a STOP or E-stop is in force, and if one appears mid-run it stops and puts the starting limits back.
	268
	269	## Sensors & dosing (parts list, and the controller)
	270
	271	`src/doser.ts` is the dose controller: three loops (nutrient A, nutrient B, pH down), each `off`, `suggest` (default) or `auto`, with per-dose and per-day ml limits, a ≥10 min mixing wait, no dose on a stale (>30 min), uncalibrated or already-used reading, and a halt until the owner resumes when a reading is out of physical bounds or a dose did not move it. Every dose goes in the log book with its cause (rule, crew, owner). `topOff` runs the fresh-water pump until the high float or a time cap. Sensor and pump drivers are separate pulls and plug in as `Reading` sources and `Pump`s.
	272
	273	Using it today. The app builds the controller at boot over the Pi's real pumps (below); readings are the newest measurements in the log book. State (the day's doses, the stop, each loop's mode) is kept in `dosing.json` under `FORGE_APP_DATA` and survives a restart.
	274	- Page: the owner sees a Dosing card on `/care`: each loop, its mode, what it would add, a Do it button, a mode picker, and a red "Dosing stopped" banner with Resume dosing. Guests and non-owners see nothing.
	275	- Terminal: `/care dosing`, `/care dose <nutrientA\|nutrientB\|phDown> [ml]`, `/care mode <loop> <off\|suggest\|auto>`, `/care resume`. The server decides who may; all four are the owner's.
	276	- Crew (MCP): `POST /care/mcp` speaks JSON-RPC (`initialize`, `tools/list`, `tools/call`) with the tools `readings`, `log`, `suggest_dose` and `dose`. A crew dose is refused unless the owner put that loop in `auto`, and is bound by the same limits. The crew cannot change a mode or resume.
	277	Who may call: every call needs a verified identity (the forge-signed header), or it gets 401, `tools/list` included. `readings` and `log` are for anyone signed in; `suggest_dose`, `dose` and `pumps` are the owner's (403 otherwise), like the card on `/care`. A crew agent calls with the owner's identity, and its dose is still the crew's: refused unless the loop is in `auto`. At most 60 calls a minute per identity (429).
	278	- Owner-only: `setMode` and `resume` take the caller's cause and throw for anything but the owner. Modes are never raised by a rule or an agent.
	279
	280	The pumps (`src/dose-pumps.ts` on the Pi, `src/arm-pumps.ts` in the relay). The arm server runs the four pumps (nutrient A, nutrient B, pH down, top-off), like the grow light: each pump's switch is a GPIO line to a relay or MOSFET channel, or a Shelly plug (the light's drivers, `src/light-switch.ts`; a USB port can't carry a 12 V pump, so uhubctl isn't offered). Each pump turns ml into seconds with its own measured ml/s. Settings and the day's runs are kept in `dose-pumps.json` beside the arm's other data.
	281	- Set up, on `/care` → Dosing → Pumps (owner only): Wire a pump (GPIO line, tick "closes on 0" for an active-low board, or a plug address). Tap Run 10 s into a measuring cup (also primes the tube), type the ml the cup caught, and Save calibration: 12 ml in 10 s is 1.2 ml/s. A new switch clears the calibration. For top-off, set the high float's GPIO line and the time cap (5–600 s, 120 by default), then Top off now: it runs until the float says full or the cap passes, and the log book gets topoff, or a note to check the jug when the cap stopped it.
	282	- Terminal: `/care pumps`, `/care wire <pump> gpio <line> [low]` · `shelly <host>` · `none`, `/care prime <pump> [seconds]`, `/care calibrate <pump> <ml>`, `/care float <line\|none> [low] [cap seconds]`, `/care topoff`. A pump is `nutrientA`, `nutrientB`, `phDown` or `topOff`.
	283	- Crew (MCP): the `pumps` tool reads each pump's switch, ml/s, calibration date, today's ml and the float. The crew can't wire, prime, calibrate or top off.
	284	- Refused, not failed: a pump with no switch or no calibration, or a dose past the Pi's own backstop (60 s in one run, 100 ml a pump a day, whatever the controller asks) answers 409 before anything switches. The controller then refuses that dose without counting it or stopping automation. A switch that fails once it was asked to close is a failure: the pump is switched off anyway (three tries), and dosing stops until the owner resumes.
	285	- Off, always: every wired pump is switched off when the arm server starts, and after every run, including one that throws.
	286	- Only the relay asks the Pi: the relay answers `/grow/dosing` from a browser with 404, owner or not, so no dose skips the controller's limits. The Pi's `GET`/`POST /grow/dosing` aren't gated on the arm server itself, like `/grow/light`: whoever reaches the arm server's port reaches them, and the backstop above is what holds there.
	287
	288	\| Part \| Module \| Wiring \| Price \|
	289	\|---\|---\|---\|---\|
	290	\| Water temperature \| DS18B20 waterproof, 4.7 kΩ pull-up \| 1-Wire on GPIO4 \| ~$4 \|
	291	\| Air temp/humidity \| SHT31 or BME280 breakout \| I²C SDA/SCL (GPIO2/3), 3.3 V \| ~$8 \|
	292	\| ADC for probes \| ADS1115 \| I²C 0x48 \| ~$7 \|
	293	\| pH probe + board \| analog pH kit (BNC) \| ADS1115 A0 \| ~$30 \|
	294	\| EC probe + board \| analog EC K=1 kit \| ADS1115 A1 \| ~$40 \|
	295	\| Reservoir level \| float switch (low), second float (high, for top-off) \| GPIO17, GPIO27 to GND \| ~$3 each \|
	296	\| Dosing pumps ×3 \| 12 V peristaltic, with a 4-channel MOSFET/relay board \| GPIO22/23/24 → board, 12 V supply \| ~$12 each + ~$6 \|
	297	\| Top-off pump \| 12 V diaphragm or peristaltic, jug of fresh water \| GPIO25 → fourth channel \| ~$10 \|
	298	\| 12 V supply \| 12 V 2 A \| to the board, not the Pi \| ~$10 \|
		@@ -80,6 +80,6 @@ const facts = new Facts({ file: join(dir, "facts.sqlite") });
80	80	const piSync = piSyncFromEnv(process.env, remote?.http ?? null, remote?.host ?? null, () => lobby.turns.snapshot().driver === null, dir);
81	81	const grow = { stills: new GrowStills(join(dir, "grow-stills"), { capBytes: Number(process.env.GROW_STILLS_CAP_MB) * 1e6 \|\| undefined }), log: new GrowLog(join(dir, "grow-log.json")), everyMs: parseEvery(process.env.GROW_STILL_MINUTES) };
82	82	const careProfile = loadProfiles(BUILT_IN_DIR, join(dir, "care-profiles")).find((p) => p.id === (process.env.CARE_PROFILE ?? "spinach"));
83		const relay = await startRelay({ probeEveryMs: 300_000, sensorsMs: 600_000, care: careProfile ? { log: new CareLog(join(dir, "care.json")), profile: careProfile } : undefined, grow, stations: new StationHub(join(dir, "stations.json")), facts, piSync: piSync ?? undefined, host, port, simulation: `http://127.0.0.1:${simulation.port}`, remote, problem, lobby, cameras, leaders, video, summaryEveryMs: 60_000, holdFile: join(dir, "hold.json"), baselineFile: join(dir, "servo-factory.json") });
	83	const relay = await startRelay({ probeEveryMs: 300_000, sensorsMs: 600_000, care: careProfile ? { log: new CareLog(join(dir, "care.json")), profile: careProfile, dosingFile: join(dir, "dosing.json") } : undefined, grow, stations: new StationHub(join(dir, "stations.json")), facts, piSync: piSync ?? undefined, host, port, simulation: `http://127.0.0.1:${simulation.port}`, remote, problem, lobby, cameras, leaders, video, summaryEveryMs: 60_000, holdFile: join(dir, "hold.json"), baselineFile: join(dir, "servo-factory.json") });
84	84	const { mode, host: armHost } = relay.link();
85	85	console.log(`arm on http://${host}:${relay.port} (${mode === "simulated" ? "simulated" : `arm ${armHost}: ${mode}`}; data in ${dir}${local ? "; local: every visitor drives as the owner" : ""})`);
		@@ -0,0 +1,136 @@
	1	/**
	2	* The relay's side of the dosing pumps, which live on the arm server (src/dose-pumps.ts on the Pi):
	3	* armPumps the controller's Pump for each loop: a dose is POST /grow/dosing {"action": "dose"}; a 409 (nothing ran)
	4	* becomes PumpRefused, anything else a failure that halts automation
	5	* readDosing GET /grow/dosing read field by field, so a wrong answer shows as less, never as markup or a crash
	6	* pumpRequest the owner's setup forms (wire, float, prime, calibrate, top off) as the Pi's JSON; never a dose, which
	7	* goes through the controller's limits alone
	8	*/
	9	import { LOOPS, PumpRefused, type LoopId, type Pump } from "./doser.ts";
	10	import { PUMP_IDS, type DosingView, type FloatConfig, type PumpId, type PumpView } from "./dose-pumps.ts";
	11
	12	export type PumpAnswer = { ok: true; body: unknown } \| { ok: false; status: number; error: string };
	13
	14	/** How the relay reaches the Pi's pumps; `status` 0 is no answer. */
	15	export interface PumpHooks {
	16	read(): Promise<DosingView \| null>;
	17	write(body: Record<string, unknown>, timeoutMs: number): Promise<PumpAnswer>;
	18	}
	19
	20	/** Room for the Pi's longest dose (60 s) and its longest top-off (600 s), and the trip. */
	21	export const DOSE_TIMEOUT_MS = 75_000;
	22	export const FILL_TIMEOUT_MS = 620_000;
	23
	24	export const PUMP_LABEL: Record<PumpId, string> = { nutrientA: "Nutrient A", nutrientB: "Nutrient B", phDown: "pH down", topOff: "Top-off" };
	25
	26	export function armPumps(hooks: PumpHooks): Record<LoopId, Pump> {
	27	const pump = (id: LoopId): Pump => ({
	28	async dose(ml) {
	29	const a = await hooks.write({ action: "dose", pump: id, ml }, DOSE_TIMEOUT_MS);
	30	if (a.ok) return;
	31	if (a.status === 409) throw new PumpRefused(a.error);
	32	throw new Error(a.error);
	33	},
	34	});
	35	return Object.fromEntries(LOOPS.map((l) => [l, pump(l)])) as Record<LoopId, Pump>;
	36	}
	37
	38	const obj = (v: unknown): Record<string, unknown> => (typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : {});
	39	const text = (v: unknown, max: number): string => (typeof v === "string" ? v.replace(/[\p{Cc}\p{Cf}]/gu, "").slice(0, max) : "");
	40	const num = (v: unknown): number \| null => (typeof v === "number" && Number.isFinite(v) ? v : null);
	41	const pumpId = (v: unknown): PumpId \| null => (PUMP_IDS.includes(v as PumpId) ? (v as PumpId) : null);
	42
	43	export function readDosing(body: unknown): DosingView \| null {
	44	const b = obj(body);
	45	if (!Array.isArray(b.pumps)) return null;
	46	const pumps: PumpView[] = b.pumps.flatMap((x: unknown) => {
	47	const p = obj(x);
	48	const id = pumpId(p.id);
	49	const driver = text(p.driver, 20);
	50	return id ? [{ id, driver: driver === "gpio" \|\| driver === "shelly" ? driver : null, mlPerSec: num(p.mlPerSec), calibratedAt: num(p.calibratedAt), dosedTodayMl: num(p.dosedTodayMl) ?? 0 }] : [];
	51	});
	52	const f = obj(b.float);
	53	const float: FloatConfig \| null = typeof f.chip === "string" && /^gpiochip\d{1,2}$/.test(f.chip) && Number.isInteger(f.line) ? { chip: f.chip, line: f.line as number, activeLow: f.activeLow === true } : null;
	54	const pr = obj(b.primed);
	55	const primedPump = pumpId(pr.pump);
	56	return {
	57	pumps,
	58	float,
	59	full: typeof b.full === "boolean" ? b.full : null,
	60	capSec: num(b.capSec) ?? 0,
	61	primed: primedPump && num(pr.ms) !== null && num(pr.at) !== null ? { pump: primedPump, ms: pr.ms as number, at: pr.at as number } : null,
	62	running: pumpId(b.running),
	63	maxRunMs: num(b.maxRunMs) ?? 0,
	64	maxDayMl: num(b.maxDayMl) ?? 0,
	65	error: text(b.error, 300) \|\| null,
	66	};
	67	}
	68
	69	/** The setup actions the owner may ask of the Pi. `dose` is not one: a dose goes through the controller. */
	70	export const SETUP_ACTIONS = ["switch", "float", "prime", "calibrate", "fill"] as const;
	71
	72	/**
	73	* The Pi's JSON for one of the card's forms (strings) or the terminal's JSON (typed); null when it is not a setup
	74	* action. Only shape is decided here: the Pi checks every value.
	75	*/
	76	export function pumpRequest(input: Record<string, unknown>): Record<string, unknown> \| null {
	77	const get = (k: string) => (typeof input[k] === "string" ? (input[k] as string).trim() : input[k]);
	78	const n = (k: string) => {
	79	const v = get(k);
	80	return typeof v === "number" ? v : typeof v === "string" && /^\d{1,6}(\.\d{1,3})?$/.test(v) ? Number(v) : v;
	81	};
	82	const pump = get("pump");
	83	switch (get("action")) {
	84	case "switch": {
	85	if (input.switch !== undefined) return { action: "switch", pump, switch: input.switch };
	86	switch (get("driver")) {
	87	case "none":
	88	return { action: "switch", pump, switch: null };
	89	case "gpio":
	90	return { action: "switch", pump, switch: { driver: "gpio", chip: get("chip") \|\| "gpiochip0", line: n("line"), activeLow: input.activeLow === "on" \|\| input.activeLow === true } };
	91	case "shelly":
	92	return { action: "switch", pump, switch: { driver: "shelly", host: get("host"), gen: String(get("gen")) === "1" ? 1 : 2 } };
	93	default:
	94	return { action: "switch", pump, switch: { driver: get("driver") } };
	95	}
	96	}
	97	case "float": {
	98	const out: Record<string, unknown> = { action: "float" };
	99	if (get("line") === "" \|\| get("line") === "none") out.float = null;
	100	else if (get("line") !== undefined) out.float = { chip: get("chip") \|\| "gpiochip0", line: n("line"), activeLow: input.activeLow === "on" \|\| input.activeLow === true };
	101	if (get("capSec") !== undefined && get("capSec") !== "") out.capSec = n("capSec");
	102	return out;
	103	}
	104	case "prime": {
	105	const sec = n("sec");
	106	return { action: "prime", pump, ms: typeof sec === "number" ? Math.round(sec * 1000) : sec };
	107	}
	108	case "calibrate":
	109	return { action: "calibrate", pump, ml: n("ml") };
	110	case "fill":
	111	return { action: "fill" };
	112	default:
	113	return null;
	114	}
	115	}
	116
	117	/**
	118	* The Pi's pumps as the page reads them: the last answer at once when it is under `freshMs` old, a fresh read otherwise
	119	* (one in flight at a time). The very first read waits at most `firstWaitMs`, so a Pi that is down never holds /care up.
	120	*/
	121	export function cachedRead(read: () => Promise<DosingView \| null>, freshMs = 5000, now: () => number = Date.now, firstWaitMs = 300) {
	122	let last: { at: number; view: DosingView \| null } \| null = null;
	123	let inflight: Promise<DosingView \| null> \| null = null;
	124	const refresh = (): Promise<DosingView \| null> =>
	125	(inflight ??= read()
	126	.then((view) => ((last = { at: now(), view }), view))
	127	.finally(() => (inflight = null)));
	128	return {
	129	read: async (): Promise<DosingView \| null> => {
	130	if (last && now() - last.at < freshMs) return last.view;
	131	if (last) return void refresh().catch(() => {}), last.view;
	132	return Promise.race([refresh(), new Promise<null>((r) => setTimeout(() => r(null), firstWaitMs))]);
	133	},
	134	refresh,
	135	};
	136	}
		@@ -0,0 +1,216 @@
	1	import { expect, test } from "bun:test";
	2	import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
	3	import { createServer } from "node:http";
	4	import { tmpdir } from "node:os";
	5	import { join } from "node:path";
	6	import { CareLog } from "./care-log.ts";
	7	import { fakeDoser, handleDosing, MCP_PER_MINUTE, rateLimit } from "./care-dosing.ts";
	8	import { renderCare } from "./care-page.ts";
	9	import { careCommand, dosingLines } from "./care-terminal.ts";
	10	import { BUILT_IN_DIR, loadProfiles } from "./care-profile.ts";
	11	import { Doser, LOOPS, topOff } from "./doser.ts";
	12
	13	const spinach = loadProfiles(BUILT_IN_DIR).find((p) => p.id === "spinach")!;
	14
	15	async function serve(who: "owner" \| "guest" \| "member", opts: { doser?: Doser; log?: CareLog; origin?: boolean } = {}) {
	16	const log = opts.log ?? new CareLog();
	17	const doser = opts.doser ?? fakeDoser(log);
	18	const server = createServer((req, res) => {
	19	const readBody = (r: typeof req, limit = 1 << 20) => new Promise<Buffer>((ok, no) => { const c: Buffer[] = []; let n = 0; r.on("data", (d: Buffer) => { n += d.length; if (n > limit) { no(new Error("body too large")); return; } c.push(d); }); r.on("end", () => ok(Buffer.concat(c))); });
	20	handleDosing(req, res, new URL(req.url!, "http://x").pathname, { doser, log, readBody, sameOrigin: () => opts.origin !== false, who: () => ({ owner: who === "owner", known: who !== "guest" }) }).then((hit) => hit \|\| (res.writeHead(404), res.end()));
	21	});
	22	await new Promise<void>((ok) => server.listen(0, "127.0.0.1", ok));
	23	const base = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
	24	const post = (path: string, body: unknown) => fetch(base + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
	25	return { base, log, doser, post, close: () => server.close() };
	26	}
	27
	28	test("the owner sees dosing, sets a mode, taps Do it, and resumes; the log book says it was simulated", async () => {
	29	const s = await serve("owner");
	30	try {
	31	s.log.add({ type: "measurement", kind: "ph", value: 7.2 });
	32	const state = (await (await fetch(`${s.base}/care/dosing`)).json()) as { simulated: boolean; loops: { id: string; mode: string; suggestion: { ml: number } \| null }[] };
	33	expect(state.simulated).toBe(true);
	34	const ph = state.loops.find((l) => l.id === "phDown")!;
	35	expect(ph.mode).toBe("suggest");
	36	expect(ph.suggestion!.ml).toBeGreaterThan(0);
	37	const did = await s.post("/care/dosing/dose", { loop: "phDown" });
	38	expect(did.status).toBe(200);
	39	expect(s.log.entries().at(-1)).toMatchObject({ type: "observation" });
	40	expect((await s.post("/care/dosing/mode", { loop: "phDown", mode: "auto" })).status).toBe(200);
	41	expect(s.doser.loops.phDown.mode).toBe("auto");
	42	expect((await s.post("/care/dosing/mode", { loop: "phDown", mode: "wild" })).status).toBe(400);
	43	const second = await s.post("/care/dosing/dose", { loop: "phDown" });
	44	expect(second.status).toBe(409);
	45	expect((await s.post("/care/dosing/resume", {})).status).toBe(200);
	46	const form = await fetch(`${s.base}/care/dosing/mode`, { method: "POST", redirect: "manual", headers: { "content-type": "application/x-www-form-urlencoded" }, body: "loop=phDown&mode=off" });
	47	expect(form.status).toBe(303);
	48	expect(s.doser.loops.phDown.mode).toBe("off");
	49	} finally {
	50	s.close();
	51	}
	52	});
	53
	54	test("a guest or a signed-in non-owner sees nothing and cannot dose, resume or set a mode", async () => {
	55	for (const who of ["guest", "member"] as const) {
	56	const s = await serve(who);
	57	try {
	58	expect((await fetch(`${s.base}/care/dosing`)).status).toBe(who === "guest" ? 401 : 403);
	59	for (const [path, body] of [["/care/dosing/dose", { loop: "phDown" }], ["/care/dosing/resume", {}], ["/care/dosing/mode", { loop: "phDown", mode: "auto" }]] as const) {
	60	expect((await s.post(path, body)).status).toBe(who === "guest" ? 401 : 403);
	61	}
	62	expect(s.doser.loops.phDown.mode).toBe("suggest");
	63	} finally {
	64	s.close();
	65	}
	66	}
	67	});
	68
	69	test("a write from another origin is refused, and a body over the cap is cut off", async () => {
	70	const other = await serve("owner", { origin: false });
	71	try {
	72	expect((await other.post("/care/dosing/mode", { loop: "phDown", mode: "auto" })).status).toBe(403);
	73	expect(other.doser.loops.phDown.mode).toBe("suggest");
	74	} finally {
	75	other.close();
	76	}
	77	const s = await serve("owner");
	78	try {
	79	const big = await fetch(`${s.base}/care/dosing/mode`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ loop: "phDown", mode: "auto", pad: "x".repeat(10_000) }) });
	80	expect(big.status).toBe(413);
	81	} finally {
	82	s.close();
	83	}
	84	});
	85
	86	test("crew tools over MCP, with the owner's verified identity: read and suggest, dose only in auto, never resume or set a mode", async () => {
	87	const s = await serve("owner");
	88	const call = async (name: string, args: object = {}) => ((await (await s.post("/care/mcp", { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } })).json()) as { result?: { isError: boolean; content: { text: string }[] }; error?: unknown });
	89	try {
	90	s.log.add({ type: "measurement", kind: "ph", value: 7.2 });
	91	const list = (await (await s.post("/care/mcp", { jsonrpc: "2.0", id: 1, method: "tools/list" })).json()) as { result: { tools: { name: string }[] } };
	92	expect(list.result.tools.map((t) => t.name)).toEqual(["readings", "log", "suggest_dose", "dose", "pumps"]);
	93	expect(JSON.parse((await call("readings")).result!.content[0]!.text).ph.value).toBe(7.2);
	94	expect(JSON.parse((await call("suggest_dose", { loop: "phDown" })).result!.content[0]!.text).ml).toBeGreaterThan(0);
	95	const refused = await call("dose", { loop: "phDown" });
	96	expect(refused.result!.isError).toBe(true);
	97	expect(refused.result!.content[0]!.text).toContain("only suggests");
	98	expect(s.log.entries().filter((e) => e.type !== "measurement")).toHaveLength(0);
	99	expect((await call("resume")).error).toBeDefined();
	100	expect((await call("setMode", { loop: "phDown", mode: "auto" })).error).toBeDefined();
	101	s.doser.setMode("phDown", "auto", "owner");
	102	const done = await call("dose", { loop: "phDown", ml: 2 });
	103	expect(done.result!.isError).toBe(false);
	104	const over = await call("dose", { loop: "phDown", ml: 500 });
	105	expect(over.result!.isError).toBe(true);
	106	} finally {
	107	s.close();
	108	}
	109	});
	110
	111	test("MCP without a verified identity is refused 401 on every tool, dose in auto included; a signed-in non-owner gets the log book, never dosing", async () => {
	112	const guest = await serve("guest");
	113	const rpc = (srv: typeof guest, name: string, args: object = {}) => srv.post("/care/mcp", { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } });
	114	try {
	115	guest.log.add({ type: "measurement", kind: "ph", value: 7.2 });
	116	guest.doser.setMode("phDown", "auto", "owner");
	117	for (const [name, args] of [["readings", {}], ["log", {}], ["pumps", {}], ["suggest_dose", { loop: "phDown" }], ["dose", { loop: "phDown", ml: 2 }]] as const) {
	118	const r = await rpc(guest, name, args);
	119	expect(r.status).toBe(401);
	120	}
	121	expect((await guest.post("/care/mcp", { jsonrpc: "2.0", id: 1, method: "tools/list" })).status).toBe(401);
	122	expect(guest.doser.dosedToday("phDown")).toBe(0);
	123	expect(guest.log.entries().filter((e) => e.type !== "measurement")).toHaveLength(0);
	124	} finally {
	125	guest.close();
	126	}
	127	const member = await serve("member");
	128	try {
	129	member.doser.setMode("phDown", "auto", "owner");
	130	expect((await rpc(member, "log")).status).toBe(200);
	131	for (const [name, args] of [["pumps", {}], ["suggest_dose", { loop: "phDown" }], ["dose", { loop: "phDown", ml: 2 }]] as const) expect((await rpc(member, name, args)).status).toBe(403);
	132	expect(member.doser.dosedToday("phDown")).toBe(0);
	133	} finally {
	134	member.close();
	135	}
	136	});
	137
	138	test("MCP is limited to 60 calls a minute per identity", () => {
	139	const l = rateLimit(MCP_PER_MINUTE);
	140	for (let i = 0; i < MCP_PER_MINUTE; i++) expect(l.take("a", 0)).toBe(true);
	141	expect(l.take("a", 1000)).toBe(false);
	142	expect(l.take("b", 1000)).toBe(true);
	143	expect(l.take("a", 60_000)).toBe(true);
	144	});
	145
	146	test("the care page shows the card to the owner only, with Do it and a halted banner with Resume", async () => {
	147	const log = new CareLog();
	148	log.add({ type: "measurement", kind: "ph", value: 7.2 });
	149	const doser = fakeDoser(log);
	150	const view = { profile: spinach, log, now: Date.now(), signedIn: null };
	151	const html = renderCare({ ...view, owner: true, dosing: doser.status() });
	152	expect(html).toContain("data-dosing");
	153	expect(html).toContain("Do it");
	154	expect(html).not.toContain("data-halted");
	155	expect(renderCare({ ...view, owner: false })).not.toContain("data-dosing");
	156	doser.loops.phDown.mode = "auto";
	157	await doser.dose("phDown", "rule");
	158	const later = new Doser({ pumps: { nutrientA: { dose: async () => {} }, nutrientB: { dose: async () => {} }, phDown: { dose: async () => { throw new Error("jammed"); } } }, latest: () => undefined, calibrated: () => true, log, loops: { phDown: { mode: "auto" } } });
	159	later["s"].halted = "x <b>";
	160	const stopped = renderCare({ ...view, owner: true, dosing: later.status() });
	161	expect(stopped).toContain("data-halted");
	162	expect(stopped).toContain("Resume dosing");
	163	expect(stopped).toContain("x <b>");
	164	});
	165
	166	test("the terminal words dosing as the same requests the page makes", () => {
	167	expect(careCommand(["dosing"], "")).toEqual({ method: "GET", path: "/care/dosing" });
	168	expect(careCommand(["dose", "phDown", "2"], "phDown 2")).toEqual({ method: "POST", path: "/care/dosing/dose", body: { loop: "phDown", ml: 2 }, timeoutMs: 80_000 });
	169	expect(careCommand(["mode", "phDown", "auto"], "")).toEqual({ method: "POST", path: "/care/dosing/mode", body: { loop: "phDown", mode: "auto" } });
	170	expect(careCommand(["resume"], "")).toEqual({ method: "POST", path: "/care/dosing/resume", body: {} });
	171	expect(careCommand(["dose", "water"], "")).toHaveProperty("print");
	172	expect(dosingLines({ halted: "bad", loops: [{ label: "pH down", mode: "suggest", reason: "no ph reading", dosedTodayMl: 0, maxDayMl: 15 }] })[0]).toContain("STOPPED");
	173	});
	174
	175	test("controller fixes: only the owner changes modes or resumes, modes persist, a bad file halts, a pump failure halts, a read changes nothing, top-off turns off when on() throws", async () => {
	176	const dir = mkdtempSync(join(tmpdir(), "dose-"));
	177	try {
	178	const file = join(dir, "dosing.json");
	179	const log = new CareLog();
	180	log.add({ type: "measurement", kind: "ph", value: 7.2 });
	181	const a = fakeDoser(log, file);
	182	expect(() => a.setMode("phDown", "auto", "crew")).toThrow(/owner/);
	183	expect(() => a.resume("rule")).toThrow(/owner/);
	184	a.setMode("phDown", "auto", "owner");
	185	expect(fakeDoser(log, file).loops.phDown.mode).toBe("auto");
	186
		junipercrew 16d ago `later["s"]` and `jam["d"]` reach into private fields, so the test breaks on a rename that changes no behaviour. Expose a small test seam, or build the halted state through a real failing dose.
	187	writeFileSync(file, JSON.stringify({ halted: null, lastDoseAt: 0, usedReading: {}, pending: null, doses: null, modes: {} }));
	188	expect(fakeDoser(log, file).halted).toContain("unreadable");
	189
	190	const t = Date.now();
	191	const jam = new Doser({ pumps: { nutrientA: { dose: async () => {} }, nutrientB: { dose: async () => {} }, phDown: { dose: async () => { throw new Error("jammed"); } } }, latest: () => ({ kind: "ph", value: 7.2, at: t, source: "sensor" }), calibrated: () => true, log, loops: { phDown: { mode: "auto" } }, now: () => t });
	192	const out = await jam.dose("phDown", "rule", 2);
	193	expect(out).toMatchObject({ ok: false, reason: expect.stringContaining("jammed") });
	194	expect(jam.halted).toContain("jammed");
	195	expect(jam.dosedToday("phDown")).toBe(2);
	196	expect(log.entries().at(-1)).toMatchObject({ type: "observation", text: expect.stringContaining("jammed") });
	197
	198	// a read does not halt: an out-of-bounds reading is reported by suggest, and only a dose stops automation
	199	const wild = new Doser({ pumps: jam["d"].pumps, latest: () => ({ kind: "ph", value: 99, at: t, source: "sensor" }), calibrated: () => true, log, now: () => t });
	200	expect(wild.suggest("phDown")).toHaveProperty("reason");
	201	expect(wild.halted).toBeNull();
	202	wild.loops.phDown.mode = "auto";
	203	await wild.dose("phDown", "rule", 1);
	204	expect(wild.halted).toContain("outside");
	205
	206	const calls: string[] = [];
	207	await expect(topOff({ on: async () => { calls.push("on"); throw new Error("relay"); }, off: async () => void calls.push("off") }, async () => false, { capMs: 1000 })).rejects.toThrow("relay");
	208	expect(calls).toEqual(["on", "off"]);
	209	} finally {
	210	rmSync(dir, { recursive: true, force: true });
	211	}
	212	});
	213
	214	test("the loops are the three pumps", () => {
	215	expect(LOOPS).toEqual(["nutrientA", "nutrientB", "phDown"]);
	216	});
		@@ -0,0 +1,231 @@
	1	/**
	2	* The dosing doors on the care routes: /care/dosing (state), /care/dosing/dose, /care/dosing/resume, /care/dosing/mode
	3	* (the owner's writes) and /care/mcp (the crew's tools). The limits live in src/doser.ts; this only says who may ask.
	4	* The pumps are the Pi's (src/arm-pumps.ts → src/dose-pumps.ts): /care/dosing/pump is the owner's setup of them (wire,
	5	* float, prime, calibrate, top off), never a dose. Readings are the log book's newest measurements. `fakeDoser`, whose
	6	* pumps do nothing (the log book says "simulated"), is for a relay with no pumps given.
	7	*/
	8
	9	import type { IncomingMessage, ServerResponse } from "node:http";
	10	import type { Cause, CareLog } from "./care-log.ts";
	11	import { MEASURES, type Measure } from "./care-profile.ts";
	12	import { Doser, LOOPS, type LoopId, type Mode, type Pump } from "./doser.ts";
	13	import { FILL_TIMEOUT_MS, PUMP_LABEL, pumpRequest, type PumpHooks } from "./arm-pumps.ts";
	14	import type { DosingView } from "./dose-pumps.ts";
	15
	16	export function fakeDoser(log: CareLog, file?: string, now?: () => number): Doser {
	17	const pump: Pump = { simulated: true, dose: async () => {} };
	18	return makeDoser(log, { nutrientA: pump, nutrientB: pump, phDown: pump }, file, now);
	19	}
	20
	21	/** The controller over these pumps, reading the log book's newest measurements. */
	22	export function makeDoser(log: CareLog, pumps: Record<LoopId, Pump>, file?: string, now?: () => number): Doser {
	23	return new Doser({
	24	pumps,
	25	latest: (kind: Measure) => {
	26	const m = log.entries().filter((e) => e.type === "measurement" && e.kind === kind).at(-1);
	27	return m && m.type === "measurement" ? { kind, value: m.value, at: m.at, source: m.source } : undefined;
	28	},
	29	calibrated: () => true,
	30	log,
	31	file,
	32	now,
	33	});
	34	}
	35
	36	export interface DosingContext {
	37	doser: Doser;
	38	log: CareLog;
	39	/** Who asks, from the forge-signed identity; `id` keys the MCP's rate limit. */
	40	who: (req: IncomingMessage) => { owner: boolean; known: boolean; id?: string };
	41	readBody: (req: IncomingMessage, limit?: number) => Promise<Buffer>;
	42	/** A mutation is only taken from the page's own origin (relay.ts). */
	43	sameOrigin: (req: IncomingMessage) => boolean;
	44	/** The Pi's pumps; without them there is nothing to set up. */
	45	pumps?: PumpHooks;
	46	}
	47
	48	const loopOf = (v: unknown): LoopId => {
	49	if (!LOOPS.includes(v as LoopId)) throw new Refused(`loop is one of ${LOOPS.join(", ")}`);
	50	return v as LoopId;
	51	};
	52	class Refused extends Error {}
	53
	54	/** Parse a JSON object body, capped by the bytes read. */
	55	async function object(req: IncomingMessage, ctx: DosingContext): Promise<Record<string, unknown>> {
	56	const raw = await ctx.readBody(req, 4096); // capped by the bytes read, not by a header
	57	let v: unknown;
	58	if (!(req.headers["content-type"] ?? "").includes("json")) {
	59	// the page's buttons are forms
	60	v = Object.fromEntries([...new URLSearchParams(raw.toString("utf8"))].map(([k, x]) => [k, k === "ml" ? (x === "" ? undefined : Number(x)) : x]));
	61	} else
	62	try {
	63	v = JSON.parse(raw.toString("utf8") \|\| "null");
	64	} catch {
	65	throw new Refused("send JSON");
	66	}
	67	if (!v \|\| typeof v !== "object" \|\| Array.isArray(v)) throw new Refused("send an object");
	68	return v as Record<string, unknown>;
	69	}
	70
	71	/** True when the path was this module's and has been answered. */
	72	export async function handleDosing(req: IncomingMessage, res: ServerResponse, pathname: string, ctx: DosingContext): Promise<boolean> {
	73	if (pathname !== "/care/dosing" && !pathname.startsWith("/care/dosing/") && pathname !== "/care/mcp") return false;
	74	const json = (status: number, body: unknown) => {
	75	res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
	76	res.end(JSON.stringify(body));
	77	};
	78	if (pathname === "/care/mcp") {
	79	if (req.method !== "POST") return json(405, { error: "POST JSON-RPC here" }), true;
	80	if (!ctx.sameOrigin(req)) return json(403, { error: "not from this origin" }), true;
	81	// every call needs a verified identity: the log book and readings to read, the dosing tools only for the owner
	82	const caller = ctx.who(req);
	83	if (!caller.known) return json(401, { error: "sign in first: the care tools need a verified identity" }), true;
	84	if (!mcpLimit(ctx.doser).take(caller.id ?? "", Date.now())) return json(429, { error: `more than ${MCP_PER_MINUTE} calls a minute; wait a little` }), true;
	85	await mcp(req, res, ctx, caller.owner);
	86	return true;
	87	}
	88	const me = ctx.who(req);
	89	// dosing is the owner's to see and to change; a guest sees nothing
	90	if (!me.owner) return json(me.known ? 403 : 401, { error: "only the owner may use dosing" }), true;
	91	if (req.method === "GET" && pathname === "/care/dosing") return json(200, ctx.doser.status()), true;
	92	if (req.method === "GET" && pathname === "/care/dosing/pumps") {
	93	const v = ctx.pumps ? await ctx.pumps.read() : null;
	94	return v ? json(200, v) : json(502, { error: "the arm server did not answer" }), true;
	95	}
	96	if (req.method !== "POST") return json(405, { error: "POST here" }), true;
	97	if (!ctx.sameOrigin(req)) return json(403, { error: "only this page may change dosing" }), true;
	98	const form = !(req.headers["content-type"] ?? "").includes("json");
	99	const back = (msg?: string) => {
	100	res.writeHead(303, { location: msg ? `/care?error=${encodeURIComponent(msg)}` : "/care", "cache-control": "no-store" });
	101	res.end();
	102	};
	103	try {
	104	let result: unknown = { ok: true };
		junipercrew 16d ago `await object(req, ctx).catch(() => ({}))` swallows every body error, including `body too large`, so an oversized resume still resumes. Resume needs no body, so don't read one. Or catch only the parse errors and let the 413 through.
	105	if (pathname === "/care/dosing/resume") {
	106	await object(req, ctx).catch(() => ({}));
	107	ctx.doser.resume("owner");
	108	} else if (pathname === "/care/dosing/mode") {
	109	const b = await object(req, ctx);
	110	ctx.doser.setMode(loopOf(b.loop), b.mode as Mode, "owner");
	111	} else if (pathname === "/care/dosing/dose") {
	112	const b = await object(req, ctx);
	113	const out = await ctx.doser.dose(loopOf(b.loop), "owner", b.ml === undefined ? undefined : (b.ml as number));
	114	if (!out.ok) return form ? back(out.reason) : json(409, { error: out.reason }), true;
	115	result = out;
	116	} else if (pathname === "/care/dosing/pump") {
	117	result = await setup(await object(req, ctx), ctx);
	118	} else return json(404, { error: "no such route" }), true;
	119	if (form) back();
	120	else json(200, result);
	121	} catch (err) {
	122	if (err instanceof Refused \|\| (err instanceof Error && /^(mode\|loop) is/.test(err.message))) form ? back((err as Error).message) : json(400, { error: (err as Error).message });
	123	else if ((err as Error).message === "body too large") json(413, { error: "too long" });
	124	else throw err;
	125	}
	126	return true;
	127	}
	128
	129	/** One of the owner's setup actions, sent to the Pi; a prime or a top-off is written in the log book. */
	130	async function setup(input: Record<string, unknown>, ctx: DosingContext): Promise<unknown> {
	131	if (!ctx.pumps) throw new Refused("no pumps are reachable from here");
	132	const body = pumpRequest(input);
	133	if (!body) throw new Refused("action is switch, float, prime, calibrate or fill");
	134	const a = await ctx.pumps.write(body, body.action === "fill" ? FILL_TIMEOUT_MS : 45_000);
	135	if (!a.ok) throw new Refused(a.error);
	136	const out = a.body as { stopped?: unknown; ms?: unknown; mlPerSec?: unknown } \| null;
	137	const label = PUMP_LABEL[body.pump as keyof typeof PUMP_LABEL] ?? "";
	138	if (body.action === "fill") {
	139	const secs = Math.round(Number(out?.ms ?? 0) / 1000);
	140	ctx.log.add(out?.stopped === "full" ? { type: "action", what: "topoff", cause: "owner" } : { type: "observation", text: `Top-off stopped at its ${secs} s cap before the float said full: check the jug and the float` });
	141	} else if (body.action === "prime") ctx.log.add({ type: "observation", text: `Primed the ${label} pump for ${Number(body.ms) / 1000} s` });
	142	else if (body.action === "calibrate") ctx.log.add({ type: "observation", text: `Calibrated the ${label} pump: ${String(out?.mlPerSec)} ml/s` });
	143	return a.body;
	144	}
	145
	146	/** Calls a minute per identity on /care/mcp: enough for an agent's loop, not for hammering the Pi. */
	147	export const MCP_PER_MINUTE = 60;
	148
	149	/** A fixed one-minute window per key; the oldest keys are dropped past 1000 so the map stays small. */
	150	export function rateLimit(perMinute: number) {
	151	const seen = new Map<string, { start: number; n: number }>();
	152	return {
	153	take(key: string, now: number): boolean {
	154	const w = seen.get(key);
		junipercrew 16d ago The Pi's error text goes straight into `/care?error=`. It is escaped, but it is the tool's wording (`gpioset failed`). Translate it for the person here.
	155	if (!w \|\| now - w.start >= 60_000) {
	156	seen.delete(key);
	157	seen.set(key, { start: now, n: 1 });
	158	if (seen.size > 1000) seen.delete(seen.keys().next().value!);
	159	return true;
	160	}
	161	return ++w.n <= perMinute;
	162	},
	163	};
	164	}
	165	/** One window per controller, so each app (and each test) counts its own calls. */
	166	const mcpLimits = new WeakMap<Doser, ReturnType<typeof rateLimit>>();
	167	const mcpLimit = (d: Doser) => mcpLimits.get(d) ?? (mcpLimits.set(d, rateLimit(MCP_PER_MINUTE)), mcpLimits.get(d)!);
	168
	169	/** The tools that show or change dosing, which is the owner's like the card on /care. */
	170	const OWNER_TOOLS = new Set(["suggest_dose", "dose", "pumps"]);
	171
	172	const TOOLS = [
	173	{ name: "readings", description: "The newest reading of each measure (pH, EC, temperatures, level) with its age.", inputSchema: { type: "object", properties: {} } },
	174	{ name: "log", description: "The newest entries of the care log book.", inputSchema: { type: "object", properties: { limit: { type: "number" } } } },
	175	{ name: "suggest_dose", description: "What a dosing loop would add now, or why not. Never doses.", inputSchema: { type: "object", properties: { loop: { type: "string", enum: [...LOOPS] } }, required: ["loop"] } },
	176	{ name: "dose", description: "Dose a loop. Refused unless the owner put that loop in auto, and always bound by the per-dose and daily limits, the mixing wait and fresh readings.", inputSchema: { type: "object", properties: { loop: { type: "string", enum: [...LOOPS] }, ml: { type: "number" } }, required: ["loop"] } },
	177	{ name: "pumps", description: "The dosing pumps on the Pi: each one's switch, measured ml/s and when it was calibrated, ml today, and whether the reservoir's high float says full. Read-only.", inputSchema: { type: "object", properties: {} } },
	178	];
	179
	180	/** A minimal MCP over JSON-RPC: initialize, tools/list, tools/call. A dose here is the crew's; it cannot resume or change a mode. */
	181	async function mcp(req: IncomingMessage, res: ServerResponse, ctx: DosingContext, owner: boolean) {
	182	const reply = (status: number, body: unknown) => {
	183	res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
	184	res.end(JSON.stringify(body));
	185	};
	186	let msg: { id?: unknown; method?: unknown; params?: Record<string, unknown> };
	187	try {
	188	msg = await object(req, ctx);
	189	} catch (err) {
	190	return reply(400, { jsonrpc: "2.0", id: null, error: { code: -32700, message: (err as Error).message } });
	191	}
	192	const id = typeof msg.id === "number" \|\| typeof msg.id === "string" ? msg.id : null;
	193	const ok = (result: unknown) => reply(200, { jsonrpc: "2.0", id, result });
	194	const text = (v: unknown, isError = false) => ok({ content: [{ type: "text", text: JSON.stringify(v) }], isError });
	195	switch (msg.method) {
	196	case "initialize":
	197	return ok({ protocolVersion: "2025-03-26", capabilities: { tools: {} }, serverInfo: { name: "arm-care", version: "1" } });
	198	case "tools/list":
	199	return ok({ tools: TOOLS });
	200	case "tools/call": {
	201	const args = (msg.params?.arguments ?? {}) as Record<string, unknown>;
	202	const cause: Cause = "crew";
	203	if (OWNER_TOOLS.has(String(msg.params?.name)) && !owner) return reply(403, { jsonrpc: "2.0", id, error: { code: -32001, message: "only the owner may use the dosing tools" } });
	204	try {
	205	switch (msg.params?.name) {
	206	case "pumps": {
	207	const v: DosingView \| null = ctx.pumps ? await ctx.pumps.read() : null;
	208	return text(v ?? { error: "the Pi did not answer" }, !v);
	209	}
	210	case "readings": {
	211	const now = Date.now();
	212	return text(Object.fromEntries(MEASURES.map((k) => { const e = ctx.log.entries().filter((x) => x.type === "measurement" && x.kind === k).at(-1); return [k, e && e.type === "measurement" ? { value: e.value, at: e.at, ageMs: now - e.at, source: e.source } : null]; })));
	213	}
	214	case "log":
	215	return text(ctx.log.entries().slice(-Math.min(Math.max(Math.floor(Number(args.limit ?? 20)) \|\| 20, 1), 100)));
	216	case "suggest_dose":
	217	return text(ctx.doser.suggest(loopOf(args.loop)));
	218	case "dose": {
	219	const out = await ctx.doser.dose(loopOf(args.loop), cause, args.ml === undefined ? undefined : (args.ml as number));
	220	return text(out, !out.ok);
	221	}
	222	}
	223	} catch (err) {
	224	return text({ error: (err as Error).message }, true);
	225	}
	226	return reply(200, { jsonrpc: "2.0", id, error: { code: -32602, message: "no such tool" } });
	227	}
	228	default:
	229	return reply(200, { jsonrpc: "2.0", id, error: { code: -32601, message: "no such method" } });
	230	}
	231	}
		@@ -9,10 +9,13 @@ import { MEASURES, type Measure } from "./care-profile.ts";
9	9
10	10	export const MAX_ENTRIES = 5000;
11	11	export const SENSOR_EVERY_MS = 3_600_000;
12		export const ACTIONS = ["sow", "water", "topoff", "change", "nutrients", "thin", "harvest", "airstone", "pumpcheck", "transplant", "done"] as const;
	12	export const ACTIONS = ["sow", "water", "topoff", "change", "nutrients", "phdown", "thin", "harvest", "airstone", "pumpcheck", "transplant", "done"] as const;
13	13	export const PROBLEMS = ["bolting", "tip burn", "root rot", "algae", "yellowing", "leggy"] as const;
14	14	export const SYSTEMS = ["vertical tower", "DWC", "NFT", "Kratky", "ebb-and-flow"] as const;
15	15	export type Action = (typeof ACTIONS)[number];
	16	/** Who or what made an action: the dose controller's rule, a crew agent, or the owner. */
	17	export const CAUSES = ["rule", "crew", "owner"] as const;
	18	export type Cause = (typeof CAUSES)[number];
16	19
17	20	/** What a sensor will also produce. */
18	21	export interface Reading {
		@@ -31,7 +34,7 @@ export interface Transplant {
31	34
32	35	export type Entry = { id: number; at: number } & (
33	36	\| ({ type: "measurement" } & Omit<Reading, "at">)
34		\| { type: "action"; what: Action; amount?: number; ref?: string; transplant?: Transplant }
	37	\| { type: "action"; what: Action; amount?: number; ref?: string; cause?: Cause; transplant?: Transplant }
35	38	\| { type: "observation"; text: string }
36	39	\| { type: "problem"; what: (typeof PROBLEMS)[number]; text?: string }
37	40	);
		@@ -87,7 +90,8 @@ export function parseEntry(input: unknown, now = Date.now()): EntryBody {
87	90	if (!/^[a-z0-9][a-z0-9-]*$/.test(ref!)) throw new LogError("ref is a reminder id");
88	91	return { ...base, ref };
89	92	}
90		return { ...base, ...(e.amount !== undefined ? { amount: positive(e.amount, "amount", 100000) } : {}) };
	93	if (e.cause !== undefined && !CAUSES.includes(e.cause as Cause)) throw new LogError(`cause is one of ${CAUSES.join(", ")}`);
	94	return { ...base, ...(e.amount !== undefined ? { amount: positive(e.amount, "amount", 100000) } : {}), ...(e.cause !== undefined ? { cause: e.cause as Cause } : {}) };
91	95	}
92	96	case "observation":
93	97	return { at, type: "observation", text: text(e.text, "text", 1000)! };
		@@ -3,6 +3,10 @@
3	3	import { boltingWatch, currentStage, health, LABELS, ago, readings, reminders, snapshot, stageAt, stageHistory, totals, transplantPrompt, type Snapshot } from "./care-rules.ts";
4	4	import { ACTIONS, PROBLEMS, SYSTEMS, type Entry, type CareLog } from "./care-log.ts";
5	5	import { MEASURES, type Band, type Measure, type Profile } from "./care-profile.ts";
	6	import type { Doser } from "./doser.ts";
	7	import type { DosingView } from "./dose-pumps.ts";
	8	import { renderPumps } from "./pumps-card.ts";
	9	import { MODES } from "./doser.ts";
6	10	import { renderSignedIn, SIGNED_IN_STYLE, type SignedIn } from "./signed-in.ts";
7	11	import { esc } from "./story-markdown.ts";
8	12
		@@ -28,6 +32,7 @@ h1 { margin: .5rem 0; } h2.first { margin-top: 0; } h2 { margin: 1.2rem 0 .5rem;
28	32	.health p { margin: .1rem 0; }
29	33	.panel { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: .6rem .8rem; margin: .6rem 0; }
30	34	ul.list { list-style: none; margin: 0; padding: 0; } ul.list li { display: flex; flex-wrap: wrap; gap: .4rem .8rem; align-items: center; justify-content: space-between; padding: .35rem 0; border-top: 1px solid var(--line); } ul.list li:first-child { border-top: 0; }
	35	details { flex-basis: 100%; } details summary { cursor: pointer; color: var(--link); min-height: 44px; display: flex; align-items: center; } h3 { font-size: 1rem; margin: 1rem 0 .3rem; }
31	36	.late { color: var(--bad); font-weight: 600; } .dim { color: var(--dim); font-size: .9rem; }
32	37	button, select, input { font: inherit; min-height: 44px; border-radius: 8px; border: 1px solid var(--line); background: var(--bg); color: var(--fg); padding: 0 .7rem; box-sizing: border-box; }
33	38	button { background: var(--accent); color: var(--on-accent); border: 0; font-weight: 650; padding: 0 1rem; }
		@@ -74,7 +79,7 @@ function describe(e: Entry): string {
74	79	case "action":
75	80	if (e.transplant) return `Transplant: ${e.transplant.system}, ${e.transplant.litres} L, ${e.transplant.sites} sites, pump ${e.transplant.pump ? "yes" : "no"}`;
76	81	if (e.what === "done") return `Done: ${e.ref}`;
77		return `${e.what}${e.amount ? ` ${e.amount}${e.what === "harvest" ? " g" : e.what === "nutrients" ? " ml" : ""}` : ""}`;
	82	return `${e.what}${e.amount ? ` ${e.amount}${e.what === "harvest" ? " g" : e.what === "nutrients" \|\| e.what === "phdown" ? " ml" : ""}` : ""}`;
78	83	}
79	84	}
80	85
		@@ -88,6 +93,10 @@ export interface CareView {
88	93	now: number;
89	94	/** May write: the owner (or a run on one's own machine). */
90	95	owner: boolean;
	96	/** The dosing card: the owner's only. */
	97	dosing?: ReturnType<Doser["status"]>;
	98	/** The Pi's pumps under the dosing card; null when the Pi did not answer. */
	99	pumps?: DosingView \| null;
91	100	signedIn: SignedIn \| null;
92	101	/** A refused form's message, shown at the top. */
93	102	error?: string \| null;
		@@ -95,7 +104,7 @@ export interface CareView {
95	104	probes?: string;
96	105	}
97	106
98		export function renderCare({ profile, log, now, owner, signedIn, error, probes = "" }: CareView): string {
	107	export function renderCare({ profile, log, now, owner, signedIn, error, dosing, pumps, probes = "" }: CareView): string {
99	108	const snap = snapshot(log);
100	109	const spans = stageHistory(profile, snap.entries, snap.startedAt);
101	110	const cur = currentStage(spans);
		@@ -117,6 +126,19 @@ ${spans.length === 1 ? `<form method="post" action="/care/log"><input type="hidd
117	126	</section>`
118	127	: "";
119	128
	129	const dosingCard = dosing
	130	? `<section class="panel" aria-labelledby="dosing" data-dosing><h2 id="dosing" style="margin-top:0">Dosing</h2>
	131	${dosing.halted ? `<p class="alert" role="alert" data-halted>Dosing stopped: ${esc(dosing.halted)}</p>${post("/care/dosing/resume", {}, "Resume dosing")}` : ""}
	132	${dosing.simulated ? `<p class="dim">No pumps are wired yet: a dose is only noted in the log book.</p>` : ""}
	133	<ul class="list">${dosing.loops
	134	.map(
	135	(l) => `<li data-loop="${esc(l.id)}"><span><strong>${esc(l.label)}</strong> · ${esc(l.mode)}<br><span class="dim">${l.suggestion ? esc(l.suggestion.text) : esc(l.reason ?? "")} · today ${l.dosedTodayMl} of ${l.maxDayMl} ml, up to ${l.maxDoseMl} ml a dose</span></span>
	136	<span>${l.suggestion && !dosing.halted ? post("/care/dosing/dose", { loop: l.id, ml: String(l.suggestion.ml) }, "Do it", "", `Do it: ${l.suggestion.text}`) : ""}
	137	<form class="inline" method="post" action="/care/dosing/mode"><input type="hidden" name="loop" value="${esc(l.id)}"><select name="mode" aria-label="Mode for ${esc(l.label)}">${MODES.map((m) => `<option value="${m}"${m === l.mode ? " selected" : ""}>${m}</option>`).join("")}</select><button class="quiet">Set</button></form></span></li>`,
	138	)
	139	.join("")}</ul>${pumps !== undefined ? renderPumps(pumps) : ""}</section>`
	140	: "";
	141
120	142	const dueRows = due
121	143	.map((d) => {
122	144	const late = d.overdueMs > 0 && !d.snoozedUntil;
		@@ -160,6 +182,7 @@ ${error ? `<p class="alert" role="alert">${esc(error)}</p>` : ""}
160	182	${prompt ? `<p class="panel" data-prompt="transplant">${esc(prompt)}</p>` : ""}${bolt ? `<p class="panel" data-prompt="bolting">${esc(bolt)}</p>` : ""}
161	183	${quick}
162	184	${probes}
	185	${dosingCard}
163	186	<h2>Reminders</h2><div class="panel"><ul class="list">${dueRows}</ul></div>
164	187	<h2>Metrics</h2>
165	188	<p class="dim">Typical ranges, not guaranteed. ${esc(profile.note)} Days since the last water change: ${sum.daysSinceChange ?? "none logged"}. Harvest so far: ${sum.harvestGrams} g. Light target ${profile.light.hours} h, warn above ${profile.light.warnAbove} h (bolting).</p>
		@@ -6,11 +6,17 @@ import { LogError, type CareLog } from "./care-log.ts";
6	6	import { renderCare } from "./care-page.ts";
7	7	import { calibrateProbe, renderProbes, type ProbeCache } from "./care-probes.ts";
8	8	import type { Profile } from "./care-profile.ts";
	9	import type { Doser } from "./doser.ts";
	10	import type { DosingView } from "./dose-pumps.ts";
9	11	import type { SignedIn } from "./signed-in.ts";
10	12
11	13	export interface CareContext {
12	14	profile: Profile;
13	15	log: CareLog;
	16	/** The dosing controller; its card on the page is the owner's (the doors are src/care-dosing.ts). */
	17	doser?: Doser;
	18	/** The Pi's pumps for the dosing card: wiring, calibration, the float. */
	19	pumps?: () => Promise<DosingView \| null>;
14	20	/** null when the request may not write; the reader is told who they are for the page. */
15	21	who: (req: IncomingMessage) => { owner: boolean; signedIn: SignedIn \| null; known: boolean };
16	22	readBody: (req: IncomingMessage, limit?: number) => Promise<Buffer>;
		@@ -46,7 +52,7 @@ export async function handleCare(req: IncomingMessage, res: ServerResponse, path
46	52
47	53	if (req.method === "GET" && pathname === "/care") {
48	54	const probes = renderProbes(ctx.probes?.peek() ?? null, me.owner);
49		send(200, "text/html; charset=utf-8", renderCare({ probes, profile: ctx.profile, log: ctx.log, now, owner: me.owner, signedIn: me.signedIn, error: new URL(req.url ?? "/", "http://x").searchParams.get("error")?.slice(0, 200) }));
	55	send(200, "text/html; charset=utf-8", renderCare({ probes, profile: ctx.profile, log: ctx.log, now, owner: me.owner, dosing: me.owner ? ctx.doser?.status() : undefined, pumps: me.owner && ctx.doser ? ((await ctx.pumps?.()) ?? null) : undefined, signedIn: me.signedIn, error: new URL(req.url ?? "/", "http://x").searchParams.get("error")?.slice(0, 200) }));
50	56	return true;
51	57	}
52	58	if (req.method === "GET" && pathname === "/care/events") {
		@@ -95,6 +95,26 @@ test("through the relay: a cross-site write is refused, a guest is 401, a plain
95	95	expect(careLines({ stage: "seedling", health: { ok: true, lines: [] }, reminders: [], entries: [] })[0]).toContain("healthy");
96	96	});
97	97
	98	test("through the terminal, a guest and a signed-in non-owner see nothing from /care dosing and /care pumps, and cannot set a pump up", async () => {
	99	const { port } = await start();
	100	const run = async (env: Record<string, string>, line: string) => {
	101	const printed: string[] = [];
	102	new Door("ws://127.0.0.1:1/live", {}, (l) => printed.push(l), null, null, null, null, null, null, null, null, null, null, null, null, careReader(env)).input(line);
	103	for (let i = 0; i < 100 && !printed.length; i++) await Bun.sleep(20);
	104	return printed;
	105	};
	106	for (const env of [terminal(port, null), terminal(port, "eve")]) {
	107	for (const line of ["/care dosing", "/care pumps", "/care prime phDown", "/care topoff", "/care dose phDown 2"]) {
	108	const out = await run(env, line);
	109	expect(out).toHaveLength(1);
	110	expect(out[0]).toMatch(/^error: only the owner may use dosing/);
	111	}
	112	}
	113	// the owner gets past the gate (the Pi here does not answer, and says so)
	114	const owner = await run(terminal(port, "trevato", "admin"), "/care dosing");
	115	expect(owner[0]).toMatch(/^Dosing running\|^STOPPED/);
	116	});
	117
98	118	test("/probes through the relay: anyone reads, the owner calibrates, a web viewer hears it live, and a Pi that is down never delays /care", async () => {
99	119	const view = (next: string \| null) => ({ present: true, error: null, ph: null, ec: null, tempC: 21, tempSource: "default", calibratedAt: { ph: null, ec: null }, next, pending: next === "ph4" });
100	120	const pi = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (req) => (new URL(req.url).pathname === "/probes/calibrate" ? Response.json(view("ph4")) : Response.json(view("ph7"))) });
		@@ -5,14 +5,19 @@
5	5
6	6	import { ACTIONS, PROBLEMS } from "./care-log.ts";
7	7	import { MEASURES } from "./care-profile.ts";
	8	import { LOOPS, MODES } from "./doser.ts";
	9	import { DOSE_TIMEOUT_MS, FILL_TIMEOUT_MS, PUMP_LABEL } from "./arm-pumps.ts";
	10	import { PUMP_IDS } from "./dose-pumps.ts";
8	11
9	12	export interface CareAsk {
10	13	method: "GET" \| "POST" \| "DELETE";
11	14	path: string;
12	15	body?: Record<string, unknown>;
	16	/** How long to wait for the answer, when longer than a read: a dose or a top-off runs a pump first. */
	17	timeoutMs?: number;
13	18	}
14	19
15		export const CARE_USAGE = "usage: /care · /care log <ph\|ec\|waterTemp\|airTemp\|level\|lightHours> <value> · /care did <action> [amount] · /care note <text> · /care problem <bolting\|tip burn\|root rot\|algae\|yellowing\|leggy> [detail] · /care done <reminder> · /care snooze <reminder> [hours] · /care delete <entry id>";
	20	export const CARE_USAGE = "usage: /care · /care log <ph\|ec\|waterTemp\|airTemp\|level\|lightHours> <value> · /care did <action> [amount] · /care note <text> · /care problem <bolting\|tip burn\|root rot\|algae\|yellowing\|leggy> [detail] · /care done <reminder> · /care snooze <reminder> [hours] · /care delete <entry id> · /care dosing · /care dose <nutrientA\|nutrientB\|phDown> [ml] · /care mode <loop> <off\|suggest\|auto> · /care resume · /care pumps · /care wire <pump> gpio <line> [low] \| shelly <host> \| none · /care prime <pump> [seconds] · /care calibrate <pump> <ml> · /care float <line\|none> [low] [cap seconds] · /care topoff (dosing is the owner's; a pump is nutrientA, nutrientB, phDown or topOff)";
16	21
17	22	export const PROBES_USAGE = "usage: /probes · /probes calibrate <ph7\|ph4\|ec1413> [solution tempC] (owner)";
18	23
		@@ -52,11 +57,79 @@ export function careCommand(words: string[], tail: string): CareAsk \| { print: s
52	57	return /^[a-z0-9-]{1,32}$/.test(a) && words.length <= 3 && (!b \|\| Number.isFinite(num(b))) ? post("/care/reminder", { id: a, action: "snooze", hours: b ? num(b) : 24 }) : usage;
53	58	case "delete":
54	59	return /^\d{1,9}$/.test(a) && words.length === 2 ? { method: "DELETE", path: `/care/log/${a}`, body: {} } : usage;
	60	case "dosing":
	61	return words.length === 1 ? { method: "GET", path: "/care/dosing" } : usage;
	62	case "dose":
	63	return (LOOPS as readonly string[]).includes(a) && words.length <= 3 && (!b \|\| Number.isFinite(num(b))) ? { ...post("/care/dosing/dose", { loop: a, ...(b ? { ml: num(b) } : {}) }), timeoutMs: DOSE_TIMEOUT_MS + 5000 } : usage;
	64	case "mode":
	65	return (LOOPS as readonly string[]).includes(a) && (MODES as readonly string[]).includes(b) && words.length === 3 ? post("/care/dosing/mode", { loop: a, mode: b }) : usage;
	66	case "resume":
	67	return words.length === 1 ? post("/care/dosing/resume", {}) : usage;
	68	case "pumps":
	69	return words.length === 1 ? { method: "GET", path: "/care/dosing/pumps" } : usage;
	70	case "wire": {
	71	const pump = (PUMP_IDS as readonly string[]).includes(a) ? a : null;
	72	const c = words[3] ?? "";
	73	if (!pump) return usage;
	74	if (b === "none" && words.length === 3) return pumpPost({ action: "switch", pump, switch: null });
	75	if (b === "gpio" && /^\d{1,2}$/.test(c) && words.length <= 5 && (words[4] === undefined \|\| words[4] === "low")) return pumpPost({ action: "switch", pump, switch: { driver: "gpio", chip: "gpiochip0", line: Number(c), activeLow: words[4] === "low" } });
	76	if (b === "shelly" && c && words.length === 4) return pumpPost({ action: "switch", pump, switch: { driver: "shelly", host: c, gen: 2 } });
	77	return usage;
	78	}
	79	case "prime":
	80	return (PUMP_IDS as readonly string[]).includes(a) && words.length <= 3 && (!b \|\| Number.isFinite(num(b))) ? pumpPost({ action: "prime", pump: a, sec: b ? num(b) : 10 }) : usage;
	81	case "calibrate":
	82	return (PUMP_IDS as readonly string[]).includes(a) && Number.isFinite(num(b)) && words.length === 3 ? pumpPost({ action: "calibrate", pump: a, ml: num(b) }) : usage;
	83	case "float": {
	84	if (a === "none" && words.length === 2) return pumpPost({ action: "float", line: "none" });
	85	if (!/^\d{1,2}$/.test(a) \|\| words.length > 4) return usage;
	86	const rest = words.slice(2);
	87	const low = rest.includes("low");
	88	const cap = rest.find((w) => w !== "low");
	89	if (cap !== undefined && !/^\d{1,3}$/.test(cap)) return usage;
	90	return pumpPost({ action: "float", line: Number(a), activeLow: low, ...(cap ? { capSec: Number(cap) } : {}) });
	91	}
	92	case "topoff":
	93	return words.length === 1 ? pumpPost({ action: "fill" }) : usage;
55	94	default:
56	95	return usage;
57	96	}
58	97	}
59	98
	99	const pumpPost = (body: Record<string, unknown>): CareAsk => ({ method: "POST", path: "/care/dosing/pump", body, timeoutMs: body.action === "fill" ? FILL_TIMEOUT_MS + 5000 : 50_000 });
	100
	101	/** GET /care/dosing/pumps as lines. */
	102	export function pumpLines(body: unknown): string[] {
	103	const b = (body ?? {}) as { pumps?: { id?: unknown; driver?: unknown; mlPerSec?: unknown; calibratedAt?: unknown; dosedTodayMl?: unknown }[]; float?: { line?: unknown; activeLow?: unknown } \| null; full?: unknown; capSec?: unknown; error?: unknown };
	104	const lines = (b.pumps ?? []).map((p) => {
	105	const label = PUMP_LABEL[p.id as keyof typeof PUMP_LABEL] ?? String(p.id);
	106	const cal = typeof p.mlPerSec === "number" ? `${p.mlPerSec} ml/s${typeof p.calibratedAt === "number" ? ` (measured ${new Date(p.calibratedAt).toISOString().slice(0, 10)})` : ""}` : p.driver ? "not calibrated" : "not wired";
	107	return ` ${label} · ${p.driver ? String(p.driver) : "no switch"} · ${cal}${p.id === "topOff" ? "" : ` · today ${String(p.dosedTodayMl)} ml`}`;
	108	});
	109	lines.unshift("Pumps");
	110	lines.push(b.float ? ` high float on GPIO ${String(b.float.line)}${b.float.activeLow ? " (low)" : ""}: ${b.full === true ? "full" : b.full === false ? "not full" : "no answer"} · top-off cap ${String(b.capSec)} s` : " no high float: top-off will not run");
	111	if (b.error) lines.push(` the Pi says: ${String(b.error)}`);
	112	return lines;
	113	}
	114
	115	/** What a setup action on the pumps answered, in a line. */
	116	export function pumpSaid(body: unknown): string {
	117	const b = (body ?? {}) as { mlPerSec?: unknown; ms?: unknown; stopped?: unknown };
	118	if (typeof b.mlPerSec === "number") return `calibrated: ${b.mlPerSec} ml/s`;
	119	if (b.stopped === "full") return `top-off: full after ${Math.round(Number(b.ms) / 1000)} s`;
	120	if (b.stopped === "cap") return `top-off: stopped at the cap after ${Math.round(Number(b.ms) / 1000)} s, not full; check the jug and the float`;
	121	if (typeof b.ms === "number") return `primed for ${b.ms / 1000} s: measure the cup, then /care calibrate <pump> <ml>`;
	122	return "pumps: done";
	123	}
	124
	125	/** GET /care/dosing as lines. */
	126	export function dosingLines(body: unknown): string[] {
	127	const b = (body ?? {}) as { halted?: unknown; simulated?: unknown; loops?: { label?: unknown; mode?: unknown; suggestion?: { text?: unknown } \| null; reason?: unknown; dosedTodayMl?: unknown; maxDayMl?: unknown }[] };
	128	const lines = [b.halted ? `STOPPED: ${String(b.halted)} (/care resume)` : "Dosing running", ...(b.simulated ? [" no pumps wired: a dose is only noted in the log book"] : [])];
	129	for (const l of b.loops ?? []) lines.push(` ${String(l.label)} · ${String(l.mode)} · ${l.suggestion ? String(l.suggestion.text) : String(l.reason ?? "")} · today ${String(l.dosedTodayMl)}/${String(l.maxDayMl)} ml`);
	130	return lines;
	131	}
	132
60	133	const day = (at: number) => new Date(at).toISOString().replace("T", " ").slice(0, 16);
61	134
62	135	/** GET /care/api as lines: the stage, the health strip, what is due, and the latest entries with their ids. */