Build a Port Heavy Vehicle Staging and Parking Allocator — implementation

## Build
Monitor Singapore public heavy vehicle park availability to plan pre-gate container truck staging. Allocate buffer parking slots to prevent congestion on port arterial corridors.

## User
Logistics Yard Master

## Workflow
1. Retrieve real-time heavy vehicle parking lot availability from data.gov.sg.
2. Compare incoming hauler arrival forecasts against port gate booking windows.
3. Determine optimal staging wait periods to prevent terminal gateway queuing.
4. Allocate nearby parking slots and dispatch staging notifications to haulers.

## Interface
Real-time staging map showing heavy vehicle park lot availability and scheduled hauler staging assignments.

## Data
Query heavy vehicle parking availability endpoints via data.gov.sg or local JSON sandbox fixtures.
Starter examples below are synthetic. They are not downloaded records.

## Source
[Singapore open data API](https://guide.data.gov.sg/developer-guide/api-overview)
Consumes Singapore data.gov.sg public heavy vehicle parking collection and dataset APIs.

## Tools
mastra-ai, pydantic, httpx.
Mastra AI orchestrates live telemetry streams, resource allocation tools, and dispatch state machines effectively.
Lightweight model for generating concise driver dispatch instructions in English and Mandarin.

## Deliverables
Submit runnable source, pinned dependencies, setup commands, a working interface, example outputs, and a recorded end-to-end demo. Include tests and an action log.

## Acceptance
- Ingest live heavy vehicle park occupancy rates from public data APIs.
- Correlate prime mover arrival times with assigned container terminal gate appointments.
- Allocate staging rest-stop slots in port-adjacent logistics parks to prevent highway shoulder queuing.
- Issue automated routing updates to truck drivers via dispatch telemetry feeds.

## Starter Examples
```json
[
  {
    "input": {
      "driver_eta": "15:00",
      "gate_booking_slot": "16:30",
      "park_capacities": [
        {
          "available_lots": 8,
          "park_id": "HVP-JURONG-EAST"
        },
        {
          "available_lots": 0,
          "park_id": "HVP-TUAS-AVE-1"
        }
      ],
      "truck_id": "SGX-5510-K"
    },
    "expected_output": {
      "assigned_staging_park": "HVP-JURONG-EAST",
      "buffer_duration_minutes": 60,
      "recommendation": "STAGE_AT_BUFFER_LOT",
      "status": "ALLOCATED"
    }
  },
  {
    "input": {
      "driver_eta": "15:45",
      "gate_booking_slot": "16:00",
      "park_capacities": [
        {
          "available_lots": 5,
          "park_id": "HVP-TUAS-AVE-1"
        }
      ],
      "truck_id": "SGX-5511-L"
    },
    "expected_output": {
      "assigned_staging_park": null,
      "buffer_duration_minutes": 0,
      "recommendation": "PROCEED_DIRECT_TO_TERMINAL",
      "status": "DIRECT_GATE_IN"
    }
  }
]
```

## Safety
Provides dispatch guidance only; drivers follow actual physical signage and municipal road rules.
Use mock external writes. Require human review before any real deployment.