The intent language
for the AI era

pactia 1.0

import @pactia/kernel;
import @pactia/rust-stack;

product FleetManagement {
  > Track vehicles and fleets. Customers see only their own vehicles.

  context fleet_audit_policy {
    path: "./context/fleet/audit-policy.md",    
  }

  #rust-stack

  @topology { mode: microservices, }

  @guide {
    > Map API errors to the platform envelope
    > Cursor pagination on every list — never offset
    > ${fleet_audit_policy} Required for admin mutation endpoints.
  }

  module fleet {

    @actor admins { role: Admin, capabilities: [manage_fleets], }
    @actor customers { role: Customer, capabilities: [track_vehicles], }

    @rule admin_only_register {
      > Only admins may register or decommission vehicles.
    }

    model {
      @enum VehicleStatus { values: [ACTIVE, INACTIVE, DECOMMISSIONED], }

      @entity Customer {
        @@pk
        id: uuid,
        name: string,
        email: string,
      }

      @entity Vehicle {
        @@pk
        id: uuid,
        customerId: uuid,
        vin: string,
        label: string,
        status: VehicleStatus,
      }

      @entity CreateVehicleRequest {
        customerId: uuid,
        vin: string,
        label: string,
      }

      @entity VehicleListResponse {
        vehicles: Vehicle[],
        @@nullable
        nextCursor: string,
      }

      @entity CreateVehicleResponse {
        vehicleId: uuid,
        vin: string,
      }
    }

    @security fleet { > All admin mutations must be audit-logged }

    service FleetService {
      #database
      > Fleet tracking API

      @auth { roles: [Customer, Admin] }

      #list
      @@output VehicleListResponse
      @api list_vehicles {
        method: GET,
        path: "/api/v1/vehicles",
      }

      @auth { roles: [Admin] }
      #create
      @@output CreateVehicleResponse
      @api create_vehicle {
        method: POST,
        path: "/api/v1/vehicles",
      }

      @test admin_registers_vehicle {
        name: "Admin registers a vehicle",
        when: "Admin is logged in and POST /api/v1/vehicles with valid body",
        then: "status is 201",
      }
    }
  }
}

pactia 1.0

import @pactia/rust-stack;

product FleetManagement {
  > Platform for tracking vehicles and managing fleets.
  > Trust is the core product value — customers must only ever see their own vehicles.
  > Every action that touches fleet data must be auditable.
  > Map all API errors to the platform envelope before returning to clients.
  > Use cursor pagination on every list endpoint — never offset.

  context fleet_audit_policy {
    path: "./context/fleet/audit-policy.md",    
  }

  @rule admin_audit_logged {
    > ${fleet_audit_policy} Required for admin mutation endpoints.
  }

  #rust-stack

  module fleet {

    > Admins manage fleets, register vehicles, and decommission vehicles.
    > Customers browse and track vehicles assigned to their account.
    > Only admins may register or decommission a vehicle.
    > All admin mutations must be audit-logged.

    > A vehicle belongs to exactly one customer.
    > VIN must be unique across the platform.
    > GPS position history is retained indefinitely for audit and dispute resolution.

    > Customers and admins can list vehicles.
    > Results are owner-scoped for customers and show the full fleet for admins.
    > Lists are cursor-paginated with a stable sort by creation time.

    > Only admins may create a vehicle.
    > Creating a vehicle requires a valid customer, VIN, label, and device binding.
    > A vehicle.created notification is emitted when registration succeeds.

    > Customers who attempt to register a vehicle receive forbidden — not found masking.
    > Duplicate VIN registration returns conflict with a clear error code.
  }
}