{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ammancarservices.com/schemas/acs-diagnose-scan-v1.json",
  "title": "ACS Diagnose Scan Record",
  "description": "Versioned record of customer context, immutable OBD evidence, deterministic assessment and constrained explanation.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "scan_id",
    "created_at",
    "status",
    "account_ref",
    "vehicle",
    "scan_context",
    "adapter",
    "obd_evidence",
    "assessment",
    "provenance",
    "sync"
  ],
  "properties": {
    "schema_version": { "const": "1.1.0" },
    "scan_id": { "$ref": "#/$defs/id" },
    "created_at": { "$ref": "#/$defs/date_time" },
    "completed_at": { "anyOf": [{ "$ref": "#/$defs/date_time" }, { "type": "null" }] },
    "status": {
      "enum": ["created", "connecting", "collecting", "assessing", "completed", "cancelled", "failed", "inconclusive"]
    },
    "account_ref": {
      "description": "Opaque internal reference. Direct customer identity is stored outside the diagnostic record.",
      "$ref": "#/$defs/id"
    },
    "vehicle": { "$ref": "#/$defs/vehicle" },
    "scan_context": { "$ref": "#/$defs/scan_context" },
    "adapter": { "$ref": "#/$defs/adapter" },
    "connection": { "$ref": "#/$defs/connection" },
    "obd_evidence": { "$ref": "#/$defs/obd_evidence" },
    "assessment": { "$ref": "#/$defs/assessment" },
    "explanation": {
      "anyOf": [{ "$ref": "#/$defs/explanation" }, { "type": "null" }]
    },
    "workshop": { "$ref": "#/$defs/workshop" },
    "provenance": { "$ref": "#/$defs/provenance" },
    "sync": { "$ref": "#/$defs/sync" },
    "errors": {
      "type": "array",
      "items": { "$ref": "#/$defs/scan_error" }
    }
  },
  "$defs": {
    "id": {
      "type": "string",
      "minLength": 8,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "date_time": { "type": "string", "format": "date-time" },
    "data_status": {
      "enum": ["observed", "customer_confirmed", "staff_confirmed", "decoded", "unavailable", "unsupported", "timeout", "malformed"]
    },
    "sourced_string": {
      "type": "object",
      "additionalProperties": false,
      "required": ["value", "source", "observed_at"],
      "properties": {
        "value": { "type": ["string", "null"], "maxLength": 256 },
        "source": { "$ref": "#/$defs/data_status" },
        "observed_at": { "$ref": "#/$defs/date_time" }
      }
    },
    "vehicle": {
      "type": "object",
      "additionalProperties": false,
      "required": ["vehicle_ref", "make", "model", "model_year", "powertrain", "vin", "registration_plate", "odometer"],
      "properties": {
        "vehicle_ref": { "$ref": "#/$defs/id" },
        "make": { "const": "Mercedes-Benz" },
        "model": { "$ref": "#/$defs/sourced_string" },
        "model_year": {
          "type": "object",
          "additionalProperties": false,
          "required": ["value", "source", "observed_at"],
          "properties": {
            "value": { "type": ["integer", "null"], "minimum": 1980, "maximum": 2100 },
            "source": { "$ref": "#/$defs/data_status" },
            "observed_at": { "$ref": "#/$defs/date_time" }
          }
        },
        "chassis_code": { "$ref": "#/$defs/sourced_string" },
        "engine_variant": { "$ref": "#/$defs/sourced_string" },
        "powertrain": {
          "type": "object",
          "additionalProperties": false,
          "required": ["value", "source", "observed_at"],
          "properties": {
            "value": { "enum": ["petrol", "diesel", "mild_hybrid", "plug_in_hybrid", "electric", "unknown"] },
            "source": { "$ref": "#/$defs/data_status" },
            "observed_at": { "$ref": "#/$defs/date_time" }
          }
        },
        "vin": {
          "type": "object",
          "additionalProperties": false,
          "required": ["value", "source", "observed_at", "matches_selected_vehicle"],
          "properties": {
            "value": { "type": ["string", "null"], "pattern": "^[A-HJ-NPR-Z0-9]{17}$" },
            "source": { "$ref": "#/$defs/data_status" },
            "observed_at": { "$ref": "#/$defs/date_time" },
            "matches_selected_vehicle": { "type": ["boolean", "null"] }
          }
        },
        "registration_plate": {
          "type": "object",
          "additionalProperties": false,
          "required": ["display_value", "normalized_value", "source", "observed_at"],
          "properties": {
            "display_value": { "type": "string", "maxLength": 32 },
            "normalized_value": { "type": "string", "maxLength": 32 },
            "source": { "enum": ["customer_confirmed", "staff_confirmed"] },
            "observed_at": { "$ref": "#/$defs/date_time" }
          }
        },
        "odometer": {
          "type": "object",
          "additionalProperties": false,
          "required": ["value", "unit", "source", "observed_at"],
          "properties": {
            "value": { "type": ["number", "null"], "minimum": 0 },
            "unit": { "enum": ["km", "mi"] },
            "source": { "enum": ["customer_confirmed", "staff_confirmed", "unavailable"] },
            "observed_at": { "$ref": "#/$defs/date_time" }
          }
        }
      }
    },
    "scan_context": {
      "type": "object",
      "additionalProperties": false,
      "required": ["stationary_confirmed", "warning_lights", "symptoms", "engine_state"],
      "properties": {
        "stationary_confirmed": { "type": "boolean" },
        "warning_lights": {
          "type": "array",
          "uniqueItems": true,
          "items": { "enum": ["none", "check_engine_steady", "check_engine_flashing", "oil_pressure", "coolant_temperature", "battery", "brake", "abs", "srs", "other", "unsure"] }
        },
        "symptoms": {
          "type": "array",
          "uniqueItems": true,
          "items": { "enum": ["none", "shaking", "rough_idle", "stalling", "power_loss", "overheating", "smoke", "fuel_smell", "unusual_noise", "hard_start", "poor_fuel_economy", "braking_concern", "other", "unsure"] }
        },
        "symptom_onset": { "enum": ["today", "days", "weeks", "after_refuel", "after_service", "after_battery_work", "unknown", "not_applicable"] },
        "customer_note": { "type": ["string", "null"], "maxLength": 1000 },
        "engine_state": { "enum": ["off", "ignition_on", "running", "unknown"] },
        "attachments": {
          "type": "array",
          "items": { "$ref": "#/$defs/attachment" }
        }
      }
    },
    "attachment": {
      "type": "object",
      "additionalProperties": false,
      "required": ["attachment_id", "type", "capture_purpose", "local_state", "customer_consented", "created_at"],
      "properties": {
        "attachment_id": { "$ref": "#/$defs/id" },
        "type": { "enum": ["dashboard_photo"] },
        "capture_purpose": { "enum": ["warning_light", "dashboard_message", "odometer_context", "other"] },
        "local_state": { "enum": ["local_only", "pending_upload", "uploaded", "deleted", "upload_failed"] },
        "customer_consented": { "const": true },
        "content_hash": { "type": ["string", "null"], "maxLength": 256 },
        "created_at": { "$ref": "#/$defs/date_time" }
      }
    },
    "adapter": {
      "type": "object",
      "additionalProperties": false,
      "required": ["adapter_ref", "model", "connection_type", "firmware_response", "ble_identifier_hash", "assigned_to_account"],
      "properties": {
        "adapter_ref": { "$ref": "#/$defs/id" },
        "model": { "type": "string", "maxLength": 128 },
        "connection_type": { "const": "ble" },
        "firmware_response": { "type": ["string", "null"], "maxLength": 256 },
        "ble_identifier_hash": { "type": "string", "minLength": 16, "maxLength": 256 },
        "assigned_to_account": { "type": "boolean" }
      }
    },
    "connection": {
      "type": "object",
      "additionalProperties": false,
      "required": ["connected_at", "disconnected_at", "vehicle_protocol", "average_latency_ms", "command_count", "timeout_count"],
      "properties": {
        "connected_at": { "anyOf": [{ "$ref": "#/$defs/date_time" }, { "type": "null" }] },
        "disconnected_at": { "anyOf": [{ "$ref": "#/$defs/date_time" }, { "type": "null" }] },
        "vehicle_protocol": { "type": ["string", "null"], "maxLength": 128 },
        "average_latency_ms": { "type": ["number", "null"], "minimum": 0 },
        "command_count": { "type": "integer", "minimum": 0 },
        "timeout_count": { "type": "integer", "minimum": 0 }
      }
    },
    "obd_evidence": {
      "type": "object",
      "additionalProperties": false,
      "required": ["mil", "dtcs", "readiness_monitors", "freeze_frames", "live_readings", "supported_pids", "raw_evidence_hash"],
      "properties": {
        "mil": {
          "type": "object",
          "additionalProperties": false,
          "required": ["status", "on", "reported_dtc_count"],
          "properties": {
            "status": { "$ref": "#/$defs/data_status" },
            "on": { "type": ["boolean", "null"] },
            "reported_dtc_count": { "type": ["integer", "null"], "minimum": 0 }
          }
        },
        "dtcs": { "type": "array", "items": { "$ref": "#/$defs/dtc" } },
        "readiness_monitors": { "type": "array", "items": { "$ref": "#/$defs/readiness_monitor" } },
        "freeze_frames": { "type": "array", "items": { "$ref": "#/$defs/freeze_frame" } },
        "live_readings": { "type": "array", "items": { "$ref": "#/$defs/measurement" } },
        "supported_pids": { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[0-9A-F]{2}:[0-9A-F]{2}$" } },
        "calibration_ids": { "type": "array", "items": { "type": "string", "maxLength": 256 } },
        "system_voltage": { "anyOf": [{ "$ref": "#/$defs/measurement" }, { "type": "null" }] },
        "raw_evidence_hash": { "type": "string", "minLength": 32, "maxLength": 256 }
      }
    },
    "dtc": {
      "type": "object",
      "additionalProperties": false,
      "required": ["code", "state", "system", "source", "observed_at"],
      "properties": {
        "code": { "type": "string", "pattern": "^[PBCU][0-9A-F]{4}$" },
        "state": { "enum": ["stored", "pending", "permanent"] },
        "system": { "enum": ["powertrain", "body", "chassis", "network", "unknown"] },
        "source": { "type": "string", "maxLength": 64 },
        "observed_at": { "$ref": "#/$defs/date_time" }
      }
    },
    "measurement": {
      "type": "object",
      "additionalProperties": false,
      "required": ["key", "value", "unit", "status", "observed_at"],
      "properties": {
        "key": { "type": "string", "pattern": "^[a-z0-9_]+$", "maxLength": 64 },
        "value": { "type": ["number", "string", "boolean", "null"] },
        "unit": { "type": ["string", "null"], "maxLength": 24 },
        "status": { "$ref": "#/$defs/data_status" },
        "observed_at": { "$ref": "#/$defs/date_time" }
      }
    },
    "freeze_frame": {
      "type": "object",
      "additionalProperties": false,
      "required": ["trigger_dtc", "frame_index", "measurements"],
      "properties": {
        "trigger_dtc": { "type": "string", "pattern": "^[PBCU][0-9A-F]{4}$" },
        "frame_index": { "type": "integer", "minimum": 0 },
        "measurements": { "type": "array", "items": { "$ref": "#/$defs/measurement" } }
      }
    },
    "readiness_monitor": {
      "type": "object",
      "additionalProperties": false,
      "required": ["key", "available", "complete"],
      "properties": {
        "key": { "type": "string", "pattern": "^[a-z0-9_]+$", "maxLength": 64 },
        "available": { "type": "boolean" },
        "complete": { "type": ["boolean", "null"] }
      }
    },
    "assessment": {
      "type": "object",
      "additionalProperties": false,
      "required": ["rules_version", "safety_status", "urgency", "drive_guidance", "confidence", "findings", "limitations", "safety_overrides"],
      "properties": {
        "rules_version": { "type": "string", "maxLength": 64 },
        "safety_status": { "enum": ["no_override", "fixed_warning", "fixed_stop"] },
        "urgency": { "enum": ["routine", "monitor", "visit_soon", "urgent", "stop_driving", "inconclusive"] },
        "recommended_timeframe": { "type": ["string", "null"], "maxLength": 128 },
        "drive_guidance": { "enum": ["normal_with_standard_caution", "monitor_symptoms", "limit_driving", "contact_acs_before_driving", "stop_safely", "cannot_advise"] },
        "confidence": { "enum": ["low", "moderate", "high"] },
        "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
        "limitations": { "type": "array", "items": { "type": "string", "maxLength": 500 } },
        "safety_overrides": { "type": "array", "items": { "$ref": "#/$defs/safety_override" } }
      }
    },
    "finding": {
      "type": "object",
      "additionalProperties": false,
      "required": ["finding_id", "category", "summary_key", "evidence_refs", "possible_areas", "requires_physical_test"],
      "properties": {
        "finding_id": { "$ref": "#/$defs/id" },
        "category": { "enum": ["engine", "emissions", "electrical", "cooling", "fuel", "communication", "other"] },
        "summary_key": { "type": "string", "pattern": "^[a-z0-9_.-]+$", "maxLength": 128 },
        "evidence_refs": { "type": "array", "minItems": 1, "items": { "type": "string", "maxLength": 256 } },
        "possible_areas": { "type": "array", "items": { "type": "string", "maxLength": 128 } },
        "requires_physical_test": { "type": "boolean" }
      }
    },
    "safety_override": {
      "type": "object",
      "additionalProperties": false,
      "required": ["rule_id", "trigger_refs", "message_key"],
      "properties": {
        "rule_id": { "type": "string", "maxLength": 128 },
        "trigger_refs": { "type": "array", "minItems": 1, "items": { "type": "string", "maxLength": 256 } },
        "message_key": { "type": "string", "maxLength": 128 }
      }
    },
    "explanation": {
      "type": "object",
      "additionalProperties": false,
      "required": ["language", "headline", "summary", "finding_explanations", "disclaimer", "generated_by"],
      "properties": {
        "language": { "enum": ["en", "ar"] },
        "headline": { "type": "string", "maxLength": 120 },
        "summary": { "type": "string", "maxLength": 800 },
        "finding_explanations": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["finding_id", "text"],
            "properties": {
              "finding_id": { "$ref": "#/$defs/id" },
              "text": { "type": "string", "maxLength": 800 }
            }
          }
        },
        "disclaimer": { "type": "string", "maxLength": 300 },
        "generated_by": {
          "type": "object",
          "additionalProperties": false,
          "required": ["provider", "model", "prompt_version", "generated_at", "schema_validated"],
          "properties": {
            "provider": { "type": "string", "maxLength": 64 },
            "model": { "type": "string", "maxLength": 128 },
            "prompt_version": { "type": "string", "maxLength": 64 },
            "generated_at": { "$ref": "#/$defs/date_time" },
            "schema_validated": { "const": true }
          }
        }
      }
    },
    "workshop": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "share_status": { "enum": ["not_shared", "customer_shared", "service_purpose", "withdrawn"] },
        "customer_action": { "enum": ["none", "callback_requested", "appointment_requested", "appointment_booked"] },
        "queue_status": { "enum": ["not_queued", "needs_review", "reviewed", "linked_to_job", "closed"] },
        "reviewed_by_staff_ref": { "anyOf": [{ "$ref": "#/$defs/id" }, { "type": "null" }] },
        "reviewed_at": { "anyOf": [{ "$ref": "#/$defs/date_time" }, { "type": "null" }] },
        "job_ref": { "anyOf": [{ "$ref": "#/$defs/id" }, { "type": "null" }] }
      }
    },
    "provenance": {
      "type": "object",
      "additionalProperties": false,
      "required": ["app_version", "platform", "rules_version", "raw_evidence_immutable", "policy_version"],
      "properties": {
        "app_version": { "type": "string", "maxLength": 64 },
        "platform": { "enum": ["ios", "android"] },
        "os_version": { "type": "string", "maxLength": 64 },
        "rules_version": { "type": "string", "maxLength": 64 },
        "raw_evidence_immutable": { "const": true },
        "policy_version": { "type": "string", "maxLength": 64 }
      }
    },
    "sync": {
      "type": "object",
      "additionalProperties": false,
      "required": ["state", "client_created_at", "upload_attempts", "last_attempt_at", "server_received_at"],
      "properties": {
        "state": { "enum": ["local_only", "pending_upload", "uploading", "uploaded", "upload_failed", "conflict"] },
        "client_created_at": { "$ref": "#/$defs/date_time" },
        "upload_attempts": { "type": "integer", "minimum": 0 },
        "last_attempt_at": { "anyOf": [{ "$ref": "#/$defs/date_time" }, { "type": "null" }] },
        "server_received_at": { "anyOf": [{ "$ref": "#/$defs/date_time" }, { "type": "null" }] },
        "idempotency_key": { "type": "string", "minLength": 8, "maxLength": 256 }
      }
    },
    "scan_error": {
      "type": "object",
      "additionalProperties": false,
      "required": ["code", "stage", "recoverable", "occurred_at"],
      "properties": {
        "code": { "type": "string", "pattern": "^[A-Z0-9_]+$", "maxLength": 64 },
        "stage": { "enum": ["permission", "discovery", "connection", "initialization", "identification", "collection", "assessment", "explanation", "storage"] },
        "recoverable": { "type": "boolean" },
        "occurred_at": { "$ref": "#/$defs/date_time" },
        "technical_detail": { "type": ["string", "null"], "maxLength": 1000 }
      }
    }
  }
}