# Vehicle OS

# VIN & Plate Identity

# VIN & Plate Identity

Vehicle OS adds a permanent VIN identity that is independent of the current plate.

## Why VIN exists

Plates can be changed. A VIN provides a stable identity for history, snapshots, access and service metadata even after a plate replacement.

## Plate aliases

Old plates can be retained as aliases/history so integrations can resolve previous identities.

Useful exports:

```lua
exports['nord_garages']:GetVehicleIdentity(plateOrVin)
exports['nord_garages']:ChangeVehiclePlate(plateOrVin, newPlate, actor)
exports['nord_garages']:CompareVehicles({ valueA, valueB })
```

Do not change a framework plate directly without also reconciling Nord Garages; use the supported export for integrated workflows.


# Snapshots & History

# Snapshots & History

Vehicle snapshots provide recoverable copies of vehicle state such as properties, health, fuel and position.

```lua
local snapshots = exports['nord_garages']:GetVehicleSnapshots(plateOrVin, 20)
local history = exports['nord_garages']:GetVehicleHistory(plateOrVin, 50)

exports['nord_garages']:RestoreVehicleSnapshot(plateOrVin, snapshotId, actor)
```

## Use cases

- Recover after a bad customization/integration write.
- Compare prior vehicle state.
- Admin investigation.
- Restore a known state without rewriting the ownership row manually.

Restores should be treated as administrative/integration operations and should be auditable via the actor value.


# Advanced Access & Collections

# Advanced Access & Collections

## Vehicle access

Vehicle OS supports additional access roles such as co-owner, family, employee, temporary and valet.

```lua
exports['nord_garages']:GrantVehicleAccess(vehicle, identifier, role, expiresAt, actor)
exports['nord_garages']:RevokeVehicleAccess(vehicle, identifier, actor)
```

Temporary access may be constrained by the configured maximum duration.

## Collections / favourites

```lua
exports['nord_garages']:SetVehicleCollection(source, vehicle, 'Daily', true)
```

Collections organize vehicles without changing ownership or garage state.


# Reservations & Physical Slots

# Reservations & Physical Slots

## Reservations

Garage reservations can reserve capacity for a vehicle/user for a limited period.

```lua
exports['nord_garages']:CreateGarageReservation(source, garageIdentifier, vehicleId, minutes)
exports['nord_garages']:GetGarageReservations(garageIdentifier)
```

Expired/invalid reservations are ignored or cleaned by the database/runtime safety logic.

## Physical slots

Vehicle OS includes a backend for named physical parking slots/floors.

```lua
exports['nord_garages']:GetGarageSlots(identifier)
exports['nord_garages']:UpsertGarageSlot(identifier, slot)
```

Slot data can include label, floor, position, allowed vehicle types, enabled state and sort order.


# Service, Insurance, Stolen & EV Data

# Service, Insurance, Stolen & EV Data

Vehicle OS exposes provider-neutral metadata APIs.

```lua
exports['nord_garages']:SetVehicleServiceData(vehicle, data, actor)
exports['nord_garages']:SetVehicleInsurance(vehicle, data, actor)
exports['nord_garages']:SetVehicleStolen(vehicle, true, actor, details)
exports['nord_garages']:SetVehicleEVData(vehicle, data, actor)
exports['nord_garages']:GetMaintenanceStatus(vehicle)
```

These APIs allow mechanic, insurance, police and EV resources to integrate without directly coupling to Nord Garages internal SQL schema.

The exact metadata object structure can be defined by the integrating provider; keep payloads JSON-serializable and avoid storing huge binary data.


# Recovery Center & Analytics

# Recovery Center & Analytics

## Recovery Center

```lua
local issues = exports['nord_garages']:GetRecoveryCenter()
exports['nord_garages']:RepairVehicleState(vehicle, action, garageIdentifier, actor)
```

The recovery system can repair stale spawning/transit states, missing garage assignments and incompatible impound assignments using normal synchronization paths.

Intentional `detached` records are not treated as recovery errors.

## Analytics

```lua
local analytics = exports['nord_garages']:GetGarageAnalytics(days)
```

Analytics data is stored separately from ownership state and is intended for operational dashboards/diagnostics.