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

packages/db/drizzle/0030_carwash_vision.sql

@@ -0,0 +1,15 @@
+-- Car Wash: advisory vehicle category from vision (venue-modules.md §Vehicle category from
+-- vision). Categories map the vision vocabulary onto the site's own price categories; an
+-- order records what the camera saw, the category it suggested and the anomaly signed on a
+-- downgrade; the config carries the confidence floor. Recorded only — never blocks.
+ALTER TABLE `carwash_categories` ADD `vision_classes` text DEFAULT '[]' NOT NULL;
+--> statement-breakpoint
+ALTER TABLE `carwash_orders` ADD `vision_class` text;
+--> statement-breakpoint
+ALTER TABLE `carwash_orders` ADD `vision_confidence` real;
+--> statement-breakpoint
+ALTER TABLE `carwash_orders` ADD `vision_category_id` text;
+--> statement-breakpoint
+ALTER TABLE `carwash_orders` ADD `downgrade_event_id` text;
+--> statement-breakpoint
+ALTER TABLE `carwash_config` ADD `vision_threshold` real DEFAULT 0.8 NOT NULL;

packages/db/drizzle/meta/_journal.json

@@ -211,6 +211,13 @@
       "when": 1788690000000,
       "tag": "0029_role_jobs",
       "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "6",
+      "when": 1788700000000,
+      "tag": "0030_carwash_vision",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema.ts

@@ -1,5 +1,5 @@
 import { sql } from "drizzle-orm";
-import { blob, integer, primaryKey, sqliteTable, text, unique } from "drizzle-orm/sqlite-core";
+import { blob, integer, primaryKey, real, sqliteTable, text, unique } from "drizzle-orm/sqlite-core";
 
 // Schema notes:
 // - TWO event streams, deliberately separate (see wiki/decisions/event-streams-split.md):
@@ -653,6 +653,9 @@ export const carwashCategories = sqliteTable("carwash_categories", {
   name: text("name").notNull(),
   sortOrder: integer("sort_order").notNull().default(0),
   active: integer("active", { mode: "boolean" }).notNull().default(true),
+  /** The vision vocabulary classes this category covers (JSON array of VehicleClass) —
+   *  the site's own mapping ("car, sedan → Vetura"). Empty = never suggested by vision. */
+  visionClasses: text("vision_classes", { mode: "json" }).$type<string[]>().notNull().default(sql`'[]'`),
   createdAt: text("created_at")
     .notNull()
     .default(sql`(current_timestamp)`),
@@ -723,6 +726,13 @@ export const carwashOrders = sqliteTable("carwash_orders", {
   voidAt: text("void_at"),
   voidBy: text("void_by"),
   voidReason: text("void_reason"),
+  // Vision, advisory (venue-modules.md §Vehicle category): what the camera saw at entry,
+  // the category the site mapping suggested, and the `anomaly` signed when the operator
+  // chose a cheaper category above the confidence threshold. Never a tariff input.
+  visionClass: text("vision_class"),
+  visionConfidence: real("vision_confidence"),
+  visionCategoryId: text("vision_category_id"),
+  downgradeEventId: text("downgrade_event_id"),
 });
 
 /** Module-level settings singleton (id = 1). `payAt`: where wash money is taken at this
@@ -730,6 +740,8 @@ export const carwashOrders = sqliteTable("carwash_orders", {
 export const carwashConfig = sqliteTable("carwash_config", {
   id: integer("id").primaryKey(),
   payAt: text("pay_at", { enum: ["booth", "bay"] }).notNull().default("booth"),
+  /** Confidence floor (0–1) for a vision class to flag a category downgrade. */
+  visionThreshold: real("vision_threshold").notNull().default(0.8),
   updatedAt: text("updated_at"),
   updatedBy: text("updated_by"),
 });

packages/shared/src/index.ts

@@ -446,6 +446,10 @@ export const REASON_CODES = [
   // ticket (e.g. a motion radar dropped the stationary car and re-armed the button).
   // Post-hoc + advisory (ANPR never gates); the operator voids the duplicate.
   "entry.duplicatePlate",
+  // Car Wash: vision read the vehicle as a class that maps to a PRICIER category than the
+  // one the operator chose, above the site's confidence threshold. Recorded only (never
+  // blocks, no reason prompt — user, 2026-09-06); the reviewer sees both on one row.
+  "carwash.categoryDowngrade",
   // exit refusals
   "exit.refused.closed",
   "exit.refused.noSession",
@@ -498,6 +502,7 @@ export const REASON_EN: Record<ReasonCode, string> = {
   "entry.operatorIssued": "entry ticket issued by operator {operator} (physical button)",
   "entry.issue.noPresence": "operator entry refused — no vehicle detected at the entry",
   "entry.duplicatePlate": "possible duplicate entry — plate {plate} is already inside under ticket {otherIdentity}",
+  "carwash.categoryDowngrade": "wash category downgraded — camera saw {visionClass} ({visionCategory}), operator {operator} chose {chosenCategory}",
   "exit.refused.closed": "exit refused — session already closed",
   "exit.refused.noSession": "exit refused — no open session for ticket",
   "exit.refused.unpaid": "exit refused — not paid (take payment first)",
@@ -2024,8 +2029,31 @@ export interface ChargeLine {
 
 /** Setup → Car wash: the admin-maintained master data, as read/written by
  *  GET/PUT /api/carwash/settings. Ids are stable; names are display text. */
+/** What the vision service may call a vehicle's body type — a FIXED vocabulary the site
+ *  maps onto its own price categories (Setup → Car wash: "car, sedan, hatchback → Vetura").
+ *  Phase A (a COCO detector) only ever emits car/truck/bus/motorcycle; the finer classes
+ *  arrive with the body-type classifier (venue-modules.md §Vehicle category from vision). */
+export const VEHICLE_CLASSES = [
+  "car", "sedan", "hatchback", "suv", "minivan", "pickup", "van", "truck", "bus", "motorcycle",
+] as const;
+export type VehicleClass = (typeof VEHICLE_CLASSES)[number];
+export function isVehicleClass(v: unknown): v is VehicleClass {
+  return typeof v === "string" && (VEHICLE_CLASSES as readonly string[]).includes(v);
+}
+/** Below this confidence a vision class is shown but never flags a downgrade. Site
+ *  config (Setup → Car wash); this is the default. */
+export const CARWASH_VISION_THRESHOLD_DEFAULT = 0.8;
+
+/** The advisory vehicle read for a session, off the entry snapshot (unsigned device
+ *  event, like the plate). Never a tariff input by itself. */
+export interface VehicleRead {
+  readonly bodyType: VehicleClass;
+  readonly confidence: number;
+  readonly snapshotId: string | null;
+}
+
 export interface CarwashSettingsView {
-  readonly categories: { id: string; name: string; sortOrder: number; active: boolean }[];
+  readonly categories: { id: string; name: string; sortOrder: number; active: boolean; visionClasses: VehicleClass[] }[];
   readonly services: { id: string; name: string; sortOrder: number; active: boolean }[];
   /** One entry per priced (category, service) pair. */
   readonly prices: { categoryId: string; serviceId: string; priceMinor: number }[];
@@ -2033,6 +2061,8 @@ export interface CarwashSettingsView {
   /** Where wash money is taken at this site (booth = on the parking ticket; bay = the
    *  wash operator's till). Site-level; the desk no longer asks per order. */
   readonly payAt: CarWashPayAt;
+  /** Confidence floor for a vision class to flag a downgrade (0–1). */
+  readonly visionThreshold: number;
 }
 
 /** A wash order as the desk sees it (GET /api/carwash/orders). */
@@ -2060,6 +2090,12 @@ export interface CarwashOrderView {
   readonly validationEventId: string | null;
   readonly voidBy: string | null;
   readonly voidReason: string | null;
+  /** What the camera saw at entry (advisory), the category it mapped to, and the
+   *  anomaly signed when the operator chose a cheaper one. Null when vision read nothing. */
+  readonly visionClass: VehicleClass | null;
+  readonly visionConfidence: number | null;
+  readonly visionCategoryId: string | null;
+  readonly downgradeEventId: string | null;
 }
 
 export function isModuleId(v: unknown): v is ModuleId {