Phase 1 cost ingestion: balance + invoices + CSV parse + resource match

Three new schemas:
- cloud_balance_snapshots — hourly MTD balance/usage poll for live-accrual.
- cloud_invoices — header per provider invoice, with ingest status flags.
- cloud_cost_lines — per-line-item COGS, FK to cloud_resources where matched.

Three new Oban workers (queue: cloud_billing):
- BalanceWorker (hourly) records a snapshot.
- BillingHistoryWorker (daily) discovers invoices via /v2/customers/my/
  billing_history, upserts headers, enqueues an InvoiceIngestWorker for
  each not-yet-ingested invoice.
- InvoiceIngestWorker (per-invoice) fetches /invoices/:uuid/csv, parses
  with NimbleCSV (header-keyed so column order shifts don't break us),
  replaces the invoice's line set, then matches lines to cloud_resources
  by (kind, name) — case-insensitive, name extracted from "name (size)"
  description format.

DigitalOcean.Client gains get_balance / list_billing_history /
get_invoice_summary / fetch_invoice_csv. The CSV endpoint returns text/csv
so we bypass Req's body decoder.

Cron additions: BalanceWorker hourly at :07, BillingHistoryWorker daily
at 02:23.

API:
- GET /api/v1/billing/balance — latest snapshot, platform_admin only.
- GET /api/v1/billing/cost-lines?period=YYYY-MM-DD&kind&limit — per-line
  COGS, platform_admin only.

Live smoke against real DO billing API surfaced and fixed three CSV-format
gotchas: column headers use underscores not spaces (group_description,
project_name), USD column has $ prefix, dates use "YYYY-MM-DD HH:MM:SS
+0000" format (space separator + RFC822 offset).

Verified: 137 historical invoices discovered going back to 2014;
April 2026 invoice (33 lines, $86.92 total) ingested with 6/33 lines
matched to current cloud_resources. Unmatched lines are correctly
historic droplets, Spaces buckets (not yet synced), and GST.

NimbleCSV ~> 1.2 added as a dep.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

lib/arcadia_cloud_web/controllers/billing_controller.ex

@@ -0,0 +1,101 @@
+defmodule ArcadiaCloudWeb.BillingController do
+  @moduledoc """
+  Cost ingestion read endpoints. Phase 1 is operator-only (platform_admin).
+  Tenant-scoped per-deployment cost queries land in phase 3 with the
+  monthly_margin_rollup view.
+  """
+
+  use ArcadiaCloudWeb, :controller
+
+  alias ArcadiaCloud.Billing
+
+  def balance(conn, _params) do
+    with :ok <- require_platform_admin(conn) do
+      snap = Billing.latest_balance()
+      json(conn, %{balance: shape_balance(snap)})
+    end
+  end
+
+  def cost_lines(conn, params) do
+    with :ok <- require_platform_admin(conn) do
+      opts =
+        []
+        |> maybe_put(:period, parse_date(params["period"]))
+        |> maybe_put(:kind, params["kind"])
+        |> maybe_put(:limit, parse_int(params["limit"]) || 200)
+
+      lines =
+        Billing.list_cost_lines(opts)
+        |> Enum.map(&shape_line/1)
+
+      json(conn, %{cost_lines: lines, count: length(lines)})
+    end
+  end
+
+  # ---- helpers --------------------------------------------------------------
+
+  defp require_platform_admin(conn) do
+    identity = conn.assigns.current_identity
+
+    if is_list(identity.roles) and "platform_admin" in identity.roles do
+      :ok
+    else
+      conn
+      |> put_status(:forbidden)
+      |> json(%{error: "platform_admin_required"})
+      |> halt()
+    end
+  end
+
+  defp shape_balance(nil), do: nil
+
+  defp shape_balance(s) do
+    %{
+      provider: s.provider,
+      month_to_date_balance_cents: s.month_to_date_balance_cents,
+      account_balance_cents: s.account_balance_cents,
+      month_to_date_usage_cents: s.month_to_date_usage_cents,
+      generated_at: s.generated_at
+    }
+  end
+
+  defp shape_line(l) do
+    %{
+      id: l.id,
+      invoice_id: l.invoice_id,
+      resource_id: l.resource_id,
+      invoice_period: l.invoice_period,
+      kind: l.kind,
+      description: l.description,
+      qty: l.qty,
+      unit: l.unit,
+      amount_cents: l.amount_cents,
+      project_name: l.project_name,
+      category: l.category,
+      matched_at: l.matched_at
+    }
+  end
+
+  defp parse_date(nil), do: nil
+  defp parse_date(""), do: nil
+
+  defp parse_date(str) do
+    case Date.from_iso8601(str) do
+      {:ok, d} -> d
+      _ -> nil
+    end
+  end
+
+  defp parse_int(nil), do: nil
+  defp parse_int(""), do: nil
+
+  defp parse_int(str) when is_binary(str) do
+    case Integer.parse(str) do
+      {n, _} -> n
+      :error -> nil
+    end
+  end
+
+  defp maybe_put(opts, _key, nil), do: opts
+  defp maybe_put(opts, key, value), do: Keyword.put(opts, key, value)
+end