feat(carwash): advisory vehicle category from the entry camera — mapping, pre-select, downgrade flag

The app plumbing for venue-modules.md §"Vehicle category from vision"; the model is the
open half (no bundled recognizer emits body_type yet, so the desk shows nothing until
phase A lands in the vision service).

- Shared: VEHICLE_CLASSES vocabulary, VehicleRead, CARWASH_VISION_THRESHOLD_DEFAULT,
  reason code carwash.categoryDowngrade; settings/order/lookup views carry the read.
- Vision contract: /analyze vehicle.body_type + confidence (service schema); the Node
  client normalises to the vocabulary and drops the rest.
- Record: snapshot.ts stores the read in the plate's device_events row (or its own when
  the plate was unreadable); vehicleForIdentity() resolves it like the plate.
- Car wash: carwash_categories.vision_classes (site mapping "car, sedan → Vetura"),
  carwash_config.vision_threshold (signed config_change when it moves), four vision
  columns on orders — migration 0030. Lookup returns vision + suggestedCategoryId.
- Desk pre-selects the mapped category and shows the read + snapshot thumbnail; Setup
  offers class chips per category and the threshold. Operator decides.
- Flag: a read at/above the threshold whose mapped category prices HIGHER than the chosen
  one signs one `anomaly` (both categories/prices, operator, snapshot) and stores its id on
  the order. Equal/upgrade/unsure/unmapped → nothing. Recorded only, never blocks, no
  reason prompt (user, 2026-09-06).

Tests in carwash.test.ts; wiki venue-modules (As built), opencv-anpr-service, log.

Claude-Session: https://claude.ai/code/session_01FWncR69HgGPuei1dLrW3cU

apps/server/src/modules/carwash/carwash.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { createTestDb } from "@parking/db/testing";
-import { type Db } from "@parking/db";
+import { deviceEvents, type Db } from "@parking/db";
 import type { FastifyInstance } from "fastify";
 import { buildServer } from "../../server.js";
 import { login, makeLog, minutesAgo, seedTariff, seedUser } from "../../test-helpers.js";
@@ -560,3 +560,87 @@ describe("a shift's activity log is per till", () => {
     expect((await app.inject({ method: "GET", url: "/api/events", headers: { cookie: c.cookie } })).statusCode).toBe(403);
   });
 });
+
+describe("vision category — advisory, flagged, never authoritative", () => {
+  /** What snapshot.ts records when vision classifies the entry frame. */
+  function seeVehicle(identity: string, bodyType: string, bodyConfidence: number) {
+    db.insert(deviceEvents).values({
+      id: `read-${identity}-${bodyType}`, deviceId: "cam-1", category: "camera", kind: "read",
+      detail: { identity, direction: "entry", bodyType, bodyConfidence, snapshotId: "snap-1", source: "entry-exit-snapshot" },
+      occurredAt: new Date().toISOString(),
+    }).run();
+  }
+  async function mapClasses(a: Auth, ids: { car: string; suv: string }) {
+    const cur = (await app.inject({ method: "GET", url: "/api/carwash/settings", headers: { cookie: a.cookie } })).json();
+    const r = await app.inject({
+      method: "PUT", url: "/api/carwash/settings", headers: hdrs(a),
+      payload: {
+        categories: cur.categories.map((c: { id: string }) => ({ ...c, visionClasses: c.id === ids.suv ? ["suv", "pickup"] : c.id === ids.car ? ["car", "sedan", "hatchback"] : [] })),
+        visionThreshold: 0.75,
+      },
+    });
+    expect(r.statusCode).toBe(200);
+    return r.json();
+  }
+
+  it("Setup maps the vocabulary onto site categories; the lookup suggests the mapped category", async () => {
+    const a = await admin();
+    seedTariff(db);
+    const ids = await seedSettings(a);
+    const saved = await mapClasses(a, ids);
+    expect(saved.categories.find((c: { id: string }) => c.id === ids.suv).visionClasses).toEqual(["suv", "pickup"]);
+    expect(saved.visionThreshold).toBe(0.75);
+    expect((await events(a)).some((e) => e.type === "config_change" && e.payload.setting === "carwash.visionThreshold")).toBe(true);
+    const bad = await app.inject({ method: "PUT", url: "/api/carwash/settings", headers: hdrs(a), payload: { categories: [{ id: ids.car, name: "Car", visionClasses: ["spaceship"] }] } });
+    expect(bad.statusCode).toBe(400);
+
+    await openSession("T-V1");
+    seeVehicle("T-V1", "suv", 0.91);
+    const look = (await app.inject({ method: "GET", url: "/api/carwash/session/T-V1", headers: { cookie: a.cookie } })).json();
+    expect(look.vision).toEqual({ bodyType: "suv", confidence: 0.91, snapshotId: "snap-1" });
+    expect(look.suggestedCategoryId).toBe(ids.suv);
+    // Unmapped class → shown, nothing suggested.
+    await openSession("T-V2");
+    seeVehicle("T-V2", "bus", 0.99);
+    const look2 = (await app.inject({ method: "GET", url: "/api/carwash/session/T-V2", headers: { cookie: a.cookie } })).json();
+    expect(look2.vision.bodyType).toBe("bus");
+    expect(look2.suggestedCategoryId).toBeNull();
+  });
+
+  it("a confident downgrade signs an anomaly with both categories and the snapshot; equal, upgrade or unsure reads do not; the order is never blocked", async () => {
+    const a = await admin();
+    seedTariff(db);
+    const ids = await seedSettings(a);
+    await mapClasses(a, ids);
+    const order = async (identity: string, categoryId: string) => {
+      const r = await app.inject({ method: "POST", url: "/api/carwash/orders", headers: hdrs(a), payload: { identity, categoryId, serviceId: ids.std } });
+      expect(r.statusCode).toBe(201);
+      return r.json();
+    };
+    // Camera: SUV (0.91) — operator picks Car (cheaper) → flagged, recorded, still created.
+    await openSession("T-D1"); seeVehicle("T-D1", "suv", 0.91);
+    const down = await order("T-D1", ids.car);
+    expect(down).toMatchObject({ visionClass: "suv", visionConfidence: 0.91, visionCategoryId: ids.suv, categoryId: ids.car });
+    expect(down.downgradeEventId).toBeTruthy();
+    const flag = (await events(a)).find((e) => e.type === "anomaly" && e.payload.reasonCode === "carwash.categoryDowngrade")!;
+    expect(flag).toBeTruthy();
+    expect(flag.payload).toMatchObject({
+      visionClass: "suv", visionCategoryName: "SUV", chosenCategoryName: "Car", operator: "boss",
+      visionPriceMinor: 70000, chosenPriceMinor: 50000, snapshotId: "snap-1",
+    });
+    // Same category as the camera → nothing.
+    await openSession("T-D2"); seeVehicle("T-D2", "suv", 0.91);
+    expect((await order("T-D2", ids.suv)).downgradeEventId).toBeNull();
+    // Upgrade (camera Car, operator SUV) → recorded on the order, no anomaly.
+    await openSession("T-D3"); seeVehicle("T-D3", "sedan", 0.95);
+    const up = await order("T-D3", ids.suv);
+    expect(up).toMatchObject({ visionClass: "sedan", visionCategoryId: ids.car, downgradeEventId: null });
+    // Below the site threshold → shown, never flagged.
+    await openSession("T-D4"); seeVehicle("T-D4", "suv", 0.6);
+    expect((await order("T-D4", ids.car)).downgradeEventId).toBeNull();
+    // No read at all → nulls.
+    await openSession("T-D5");
+    expect(await order("T-D5", ids.car)).toMatchObject({ visionClass: null, visionCategoryId: null, downgradeEventId: null });
+    expect((await events(a)).filter((e) => e.type === "anomaly" && e.payload.reasonCode === "carwash.categoryDowngrade")).toHaveLength(1);
+  });
+});