@hed-hog/core 0.0.399 → 0.0.401

package/src/observability/monitored-cron.ts

@@ -1,4 +1,5 @@
 import * as Sentry from '@sentry/nestjs';
+import { randomUUID } from 'node:crypto';
 
 export type MonitoredCronOptions = {
   /** Slug do monitor no Sentry (Crons). */
@@ -9,34 +10,103 @@ export type MonitoredCronOptions = {
   checkinMarginMinutes?: number;
 };
 
-/** Fallback só para dimensionar o timeout da transação (ver abaixo) quando um
+/** Fallback só para dimensionar a validade da lease (ver abaixo) quando um
  * chamador futuro omitir `maxRuntimeMinutes` — os 5 crons atuais sempre informam. */
 const DEFAULT_MAX_RUNTIME_MINUTES = 5;
 
-/** Folga sobre `maxRuntimeMinutes` para o `timeout` da transação: cobre a
- * diferença entre o que o Sentry tolera (`maxRuntime`/`checkinMargin`, que só
- * marcam o check-in como perdido) e o que o Prisma de fato aborta. */
-const TRANSACTION_TIMEOUT_SLACK_MS = 30_000;
+/** Folga sobre `maxRuntimeMinutes` na validade da lease: cobre a diferença entre o
+ * que o Sentry tolera (`maxRuntime`/`checkinMargin`, que só marcam o check-in como
+ * perdido) e o instante a partir do qual outro pod pode assumir o tick. */
+const LEASE_SLACK_SECONDS = 30;
 
-/** Tempo esperando conexão do pool para abrir a transação — alinhado ao
- * `pool_timeout=20s` que packages/api-prisma/src/datasource-url.ts já aplica
- * quando PRISMA_CONNECTION_LIMIT está setado; o default do Prisma (2s) seria
- * mais apertado que esse teto que o projeto já escolheu deliberadamente. */
-const TRANSACTION_MAX_WAIT_MS = 20_000;
+/**
+ * Slugs cujo check-in de Cron Monitoring é de fato emitido, em CSV. `*` libera
+ * todos.
+ *
+ * O plano do Sentry inclui UM monitor de cron e este projeto tem cinco: os quatro
+ * que sobram tinham o check-in descartado na entrada por cota ("Usage Exceeded"),
+ * e monitor que não recebe check-in não alarma — só marca "missed" para sempre no
+ * painel, que é pior do que não existir.
+ *
+ * A vaga fica com o cron de maior cadência (1 min), porque é o que detecta mais
+ * rápido a falha que SÓ o Cron Monitoring pega: o agendador parado em todos os
+ * pods. Falha com exceção dos outros quatro continua chegando pela captura no
+ * `catch` abaixo, com a tag `cron`.
+ */
+const DEFAULT_CRON_MONITOR_SLUGS = 'sac-mailbox-poller';
+
+/** Cache pelo valor bruto: a env não muda em runtime, mas o teste troca. */
+let parsedSlugsRaw: string | undefined;
+let parsedSlugs: Set<string> = new Set();
+
+function emitsCheckIn(slug: string): boolean {
+  const raw = process.env.SENTRY_CRON_MONITOR_SLUGS ?? DEFAULT_CRON_MONITOR_SLUGS;
+
+  if (raw !== parsedSlugsRaw) {
+    parsedSlugsRaw = raw;
+    parsedSlugs = new Set(
+      raw
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean),
+    );
+  }
+
+  return parsedSlugs.has('*') || parsedSlugs.has(slug);
+}
+
+/**
+ * Identidade DESTA execução, não do pod: dois ticks seguidos no mesmo processo
+ * precisam de holders diferentes, senão um release atrasado do tick N apagaria a
+ * lease que o tick N+1 acabou de tomar.
+ */
+function newHolder(): string {
+  return `${process.env.HOSTNAME ?? 'local'}:${randomUUID()}`;
+}
+
+/**
+ * Tenta ganhar o tick com uma ÚNICA statement: quem consegue gravar
+ * `locked_until` no futuro venceu, os demais não recebem linha nenhuma de volta.
+ * Concorrentes serializam no índice único de `slug` — o perdedor reavalia o
+ * `WHERE` já com a linha do vencedor, então nunca há dois vencedores.
+ *
+ * O relógio de referência é sempre o `now()` do Postgres, dos dois lados: nenhum
+ * instante é calculado em JS, então divergência de relógio entre pods não conta.
+ */
+async function claimCronTick(
+  prisma: any,
+  slug: string,
+  holder: string,
+  leaseSeconds: number,
+): Promise<boolean> {
+  const rows: unknown[] = await prisma.$queryRaw`
+    INSERT INTO "cron_lock" ("slug", "holder", "locked_until")
+    VALUES (${slug}, ${holder}, now() + make_interval(secs => ${leaseSeconds}::double precision))
+    ON CONFLICT ("slug") DO UPDATE
+      SET "holder" = EXCLUDED."holder",
+          "locked_until" = EXCLUDED."locked_until"
+      WHERE "cron_lock"."locked_until" <= now()
+    RETURNING 1 AS won
+  `;
+
+  return rows.length > 0;
+}
 
 /**
- * Tenta ganhar o tick. Roda DENTRO da transação de `runMonitoredCron` —
- * reaproveita o MESMO padrão de `pg_try_advisory_xact_lock` já usado em
- * cms-scheduled-publisher.service.ts e class-session-reminder.service.ts, mas
- * aqui generalizado: a variante `xact` só é liberada no commit/rollback DESSA
- * transação, então segurá-la aberta pelo tempo de `work()` é o que de fato
- * garante a exclusão mútua entre pods.
+ * Devolve o tick antes do fim da lease. Sem isso o `sac-mailbox-poller` (que roda
+ * a cada minuto com lease de 2min30) só voltaria a rodar de 3 em 3 minutos.
+ *
+ * O `holder` no WHERE é o que impede liberar a lease de outra execução: se esta
+ * aqui estourou o prazo e outro pod já assumiu, o UPDATE não casa e não faz nada.
  */
-async function claimCronTick(tx: any, slug: string): Promise<boolean> {
-  const rows: { locked: boolean }[] = await tx.$queryRaw`
-    SELECT pg_try_advisory_xact_lock(hashtext(${slug})) AS locked
+async function releaseCronTick(prisma: any, slug: string, holder: string): Promise<void> {
+  await prisma.$executeRaw`
+    UPDATE "cron_lock"
+       SET "locked_until" = now()
+     WHERE "slug" = ${slug}
+       AND "holder" = ${holder}
+       AND "locked_until" > now()
   `;
-  return rows[0]?.locked === true;
 }
 
 /**
@@ -46,61 +116,83 @@ async function claimCronTick(tx: any, slug: string): Promise<boolean> {
  * simultaneamente, o Sentry recebe 2×N check-ins por execução e estoura o
  * rate limit de 6/min por monitor (ver docs/sentry.md).
  *
- * A eleição e `work()` rodam na MESMA transação interativa — é o que faz o
- * `pg_try_advisory_xact_lock` valer como exclusão mútua de verdade. Uma
- * versão anterior comitava a eleição sozinha (fora de transação): o Postgres
- * liberava o lock no instante em que a query retornava, antes do trabalho
- * real começar, e pods suficientemente próximos no tempo (o que é comum,
- * já que o @Cron dispara no mesmo segundo em todos) "ganhavam" o mesmo tick
- * e mandavam check-ins duplicados — foi o que gerou o incidente do
- * sac-sla-sweep. `work()` deliberadamente NÃO recebe `tx` (continua fechando
- * sobre `this.prisma`/outros serviços do chamador): a conexão que segura o
- * lock fica ociosa (idle in transaction) durante o trabalho real, em vez de
- * segurar locks de linha por uma chamada HTTP potencialmente longa (ex.:
- * renovação de assinatura do Graph, até 10 min).
+ * A exclusão mútua é uma LEASE na tabela `cron_lock`, não um lock de banco.
+ * Já passamos por duas versões piores:
+ *
+ * 1. `pg_try_advisory_xact_lock` numa transação que comitava logo em seguida: o
+ *    Postgres liberava o lock no instante em que a query retornava, antes do
+ *    trabalho real começar, e pods próximos no tempo (o que é comum, já que o
+ *    @Cron dispara no mesmo segundo em todos) "ganhavam" o mesmo tick — foi o
+ *    que gerou o incidente do sac-sla-sweep.
+ * 2. O mesmo lock, mas com a transação segurada durante `work()` inteiro. A
+ *    exclusão passou a valer, ao custo de manter uma conexão do pool em
+ *    `idle in transaction` por até 10 minutos. Com PRISMA_CONNECTION_LIMIT=5 por
+ *    pod e cinco crons disputando (um deles de minuto em minuto), o pool
+ *    esgotava e o próprio cron morria em "Unable to start a transaction in the
+ *    given time" — o mecanismo de observabilidade consumindo o pool de que ele
+ *    precisava (Sentry API-1H).
+ *
+ * A lease resolve as duas: a eleição é uma statement só (conexão devolvida na
+ * hora, `work()` roda sem segurar nada) e a validade gravada em `locked_until`
+ * é o que mantém os outros pods fora até o dono terminar ou o prazo vencer.
+ *
+ * Trade-off assumido: se `work()` passar de `maxRuntimeMinutes` + 30s, a lease
+ * vence e outro pod pode iniciar uma execução concorrente. A versão anterior
+ * abortava a transação no timeout — nenhum dos dois é bom, mas este não leva o
+ * pool junto.
  *
  * Quando outro pod já ganhou o tick, resolve para `undefined` sem chamar
  * `work` — não é uma falha, é a mesma semântica de "outro worker já pegou o
  * job" que a fila customizada já usa.
+ *
+ * O check-in só é emitido para os slugs de `SENTRY_CRON_MONITOR_SLUGS` (ver
+ * `DEFAULT_CRON_MONITOR_SLUGS`): a cota do plano não cobre os cinco monitores, e
+ * check-in sem cota é descartado na entrada. Tudo o mais — lease, eleição, span,
+ * captura de exceção — é igual para todos os slugs.
  */
 export async function runMonitoredCron<T>(
   prisma: any,
   options: MonitoredCronOptions,
   work: () => Promise<T>,
 ): Promise<T | undefined> {
-  const timeoutMs =
-    (options.maxRuntimeMinutes ?? DEFAULT_MAX_RUNTIME_MINUTES) * 60_000 +
-    TRANSACTION_TIMEOUT_SLACK_MS;
+  const leaseSeconds =
+    (options.maxRuntimeMinutes ?? DEFAULT_MAX_RUNTIME_MINUTES) * 60 + LEASE_SLACK_SECONDS;
+  const holder = newHolder();
 
   try {
-    return await prisma.$transaction(
-      async (tx: any) => {
-        if (!(await claimCronTick(tx, options.slug))) return undefined;
-
-        return Sentry.withMonitor(
-          options.slug,
-          () => Sentry.startSpan({ name: options.slug, op: 'cron.hedhog' }, work),
-          {
-            schedule: { type: 'crontab', value: options.schedule },
-            timezone: 'America/Sao_Paulo',
-            ...(options.maxRuntimeMinutes ? { maxRuntime: options.maxRuntimeMinutes } : {}),
-            ...(options.checkinMarginMinutes ? { checkinMargin: options.checkinMarginMinutes } : {}),
-            // Distingue cada execução do cron como um trace próprio, em vez de
-            // herdar/continuar um trace pendurado do ciclo de poll anterior.
-            isolateTrace: true,
-          },
-        );
-      },
-      { timeout: timeoutMs, maxWait: TRANSACTION_MAX_WAIT_MS },
-    );
+    if (!(await claimCronTick(prisma, options.slug, holder, leaseSeconds))) return undefined;
+
+    try {
+      const runTraced = () => Sentry.startSpan({ name: options.slug, op: 'cron.hedhog' }, work);
+
+      // Sem cota de monitor, o check-in seria descartado na entrada — o trabalho,
+      // o span e o relato de erro continuam idênticos. `startNewTrace` faz aqui o
+      // que o `isolateTrace` do withMonitor faz no outro ramo.
+      if (!emitsCheckIn(options.slug)) {
+        return await Sentry.startNewTrace(runTraced);
+      }
+
+      return await Sentry.withMonitor(options.slug, runTraced, {
+        schedule: { type: 'crontab', value: options.schedule },
+        timezone: 'America/Sao_Paulo',
+        ...(options.maxRuntimeMinutes ? { maxRuntime: options.maxRuntimeMinutes } : {}),
+        ...(options.checkinMarginMinutes ? { checkinMargin: options.checkinMarginMinutes } : {}),
+        // Distingue cada execução do cron como um trace próprio, em vez de
+        // herdar/continuar um trace pendurado do ciclo de poll anterior.
+        isolateTrace: true,
+      });
+    } finally {
+      // Best-effort: uma falha ao devolver a lease não pode virar o erro do cron
+      // (o trabalho já foi feito) e nem mascarar o erro real de `work()`. No pior
+      // caso a lease expira sozinha em `leaseSeconds`.
+      await releaseCronTick(prisma, options.slug, holder).catch(() => undefined);
+    }
   } catch (error) {
-    // withMonitor já registrou o check-in como 'error' antes de relançar (e um
-    // erro de work() também derruba a transação por rollback — inofensivo,
-    // já que nada é escrito via `tx`, só o lock é liberado). O @Cron do
-    // chamador NUNCA deve rejeitar a partir daqui: a lib `cron` por baixo do
-    // @nestjs/schedule não garante tratamento de uma rejeição vinda do
-    // onTick, e o onUnhandledRejectionIntegration({mode:'strict'}) do
-    // instrument.ts derrubaria o processo por um erro que já está capturado.
+    // withMonitor já registrou o check-in como 'error' antes de relançar. O @Cron
+    // do chamador NUNCA deve rejeitar a partir daqui: a lib `cron` por baixo do
+    // @nestjs/schedule não garante tratamento de uma rejeição vinda do onTick, e
+    // o onUnhandledRejectionIntegration({mode:'strict'}) do instrument.ts
+    // derrubaria o processo por um erro que já está capturado.
     Sentry.withScope((scope) => {
       scope.setTag('cron', options.slug);
       Sentry.captureException(error, { mechanism: { handled: true, type: 'hedhog.cron' } });

package/src/pdf/document/charts/chart-bar.ts

@@ -0,0 +1,217 @@
+import { SafeSvg } from '../pdf-document.types';
+import {
+  CHART_DEFAULT_HEIGHT,
+  CHART_FONT,
+  CHART_FULL_WIDTH,
+  ChartBaseOptions,
+  ChartSeries,
+  chartColor,
+  emptyChart,
+  legendRows,
+  line,
+  svgRoot,
+  text,
+  xAxisLabels,
+  yAxis,
+} from './chart-primitives';
+import {
+  axisLabelPlan,
+  bandScale,
+  estimateTextWidth,
+  formatNumber,
+  linearScale,
+  niceScale,
+  truncateToWidth,
+} from './chart-scale';
+
+const hasData = (series: ChartSeries[]): boolean =>
+  series.some((s) => s.values.some((v) => typeof v === 'number' && Number.isFinite(v)));
+
+const maxOf = (series: ChartSeries[], stacked: boolean): number => {
+  if (!stacked) {
+    return series.reduce(
+      (max, s) => Math.max(max, ...s.values.map((v) => (typeof v === 'number' ? v : 0))),
+      0,
+    );
+  }
+
+  const length = series.reduce((max, s) => Math.max(max, s.values.length), 0);
+  let max = 0;
+  for (let i = 0; i < length; i += 1) {
+    max = Math.max(
+      max,
+      series.reduce((sum, s) => sum + (typeof s.values[i] === 'number' ? (s.values[i] as number) : 0), 0),
+    );
+  }
+  return max;
+};
+
+/** Barras verticais, uma faixa por categoria. */
+export function barChartSvg(
+  options: ChartBaseOptions & {
+    categories: string[];
+    series: ChartSeries[];
+    stacked?: boolean;
+    yMax?: number;
+    yTicks?: number;
+    showValues?: boolean;
+    legend?: boolean;
+  },
+): SafeSvg {
+  const {
+    theme,
+    categories,
+    series,
+    stacked = false,
+    width = CHART_FULL_WIDTH,
+    height = CHART_DEFAULT_HEIGHT,
+    valueFormat = (value: number) => formatNumber(value),
+  } = options;
+
+  if (categories.length === 0 || !hasData(series)) return emptyChart(options);
+
+  const showLegend = options.legend ?? series.length > 1;
+  const legendHeight = showLegend ? 16 : 0;
+  const plot = { left: 42, right: width - 8, top: 10, bottom: height - 26 - legendHeight };
+
+  const scale = niceScale(0, options.yMax ?? maxOf(series, stacked), options.yTicks ?? 4);
+  const y = linearScale([scale.min, scale.max], [plot.bottom, plot.top]);
+  const band = bandScale(categories.length, [plot.left, plot.right]);
+
+  const parts: string[] = [
+    yAxis(scale.ticks, y, plot, theme, valueFormat),
+    line(plot.left, plot.bottom, plot.right, plot.bottom, theme.mutedFg),
+  ];
+
+  const groupWidth = stacked ? band.bandwidth : band.bandwidth / series.length;
+
+  series.forEach((serie, serieIndex) => {
+    const color = chartColor(theme, serieIndex, serie.color);
+    const stackTops = new Array(categories.length).fill(plot.bottom);
+
+    categories.forEach((_, index) => {
+      const raw = serie.values[index];
+      if (typeof raw !== 'number' || !Number.isFinite(raw)) return;
+
+      const barX = stacked ? band.band(index) : band.band(index) + groupWidth * serieIndex;
+      const top = stacked ? stackTops[index] - (plot.bottom - y(raw)) : y(raw);
+      const barHeight = Math.max(plot.bottom - y(raw), raw > 0 ? 1 : 0);
+
+      if (stacked) stackTops[index] = top;
+
+      parts.push(
+        `<rect x="${barX.toFixed(1)}" y="${top.toFixed(1)}" width="${groupWidth.toFixed(1)}" ` +
+          `height="${barHeight.toFixed(1)}" fill="${color}" rx="1.5" />`,
+      );
+
+      // O valor só entra quando cabe dentro da largura da barra; senão vira
+      // sopa de números sobrepostos.
+      if (
+        options.showValues &&
+        !stacked &&
+        estimateTextWidth(valueFormat(raw), CHART_FONT.value) < groupWidth
+      ) {
+        parts.push(
+          text(valueFormat(raw), barX + groupWidth / 2, top - 3, {
+            size: CHART_FONT.value,
+            fill: theme.ink,
+            anchor: 'middle',
+            weight: 600,
+          }),
+        );
+      }
+    });
+  });
+
+  const plan = axisLabelPlan(categories, band.bandwidth, CHART_FONT.axis);
+  parts.push(xAxisLabels(categories, band.center, plot.bottom + 12, plan, band.bandwidth, theme));
+
+  if (showLegend) {
+    const legend = legendRows(
+      series.map((serie, index) => ({
+        label: serie.name,
+        color: chartColor(theme, index, serie.color),
+      })),
+      width,
+      height - 4,
+      theme,
+    );
+    parts.push(legend.markup);
+  }
+
+  return svgRoot(width, height, parts.join(''), options.ariaLabel);
+}
+
+/**
+ * Barras horizontais — a forma certa quando o rótulo é um nome (curso, aluno),
+ * que deitado vira texto girado e ilegível.
+ */
+export function horizontalBarChartSvg(
+  options: ChartBaseOptions & {
+    categories: string[];
+    series: ChartSeries[];
+    xMax?: number;
+    labelWidth?: number;
+    showValues?: boolean;
+  },
+): SafeSvg {
+  const {
+    theme,
+    categories,
+    series,
+    width = CHART_FULL_WIDTH,
+    valueFormat = (value: number) => formatNumber(value),
+    showValues = true,
+  } = options;
+
+  if (categories.length === 0 || !hasData(series)) return emptyChart(options);
+
+  const rowHeight = 22;
+  const height = options.height ?? Math.max(categories.length * rowHeight + 24, 90);
+  const labelWidth = options.labelWidth ?? Math.min(Math.round(width * 0.34), 180);
+  const plot = { left: labelWidth + 8, right: width - 38, top: 8, bottom: height - 16 };
+
+  const scale = niceScale(0, options.xMax ?? maxOf(series, false), 4);
+  const x = linearScale([scale.min, scale.max], [plot.left, plot.right]);
+  const band = bandScale(categories.length, [plot.top, plot.bottom], 0.25);
+
+  const parts: string[] = scale.ticks.map((tick) =>
+    line(x(tick), plot.top, x(tick), plot.bottom, theme.line),
+  );
+
+  categories.forEach((category, index) => {
+    parts.push(
+      text(truncateToWidth(category, CHART_FONT.axis + 1, labelWidth), labelWidth, band.center(index) + 3, {
+        size: CHART_FONT.axis + 1,
+        fill: theme.ink,
+        anchor: 'end',
+      }),
+    );
+
+    const barHeight = band.bandwidth / series.length;
+
+    series.forEach((serie, serieIndex) => {
+      const raw = serie.values[index];
+      if (typeof raw !== 'number' || !Number.isFinite(raw)) return;
+
+      const barY = band.band(index) + barHeight * serieIndex;
+      const barWidth = Math.max(x(raw) - plot.left, raw > 0 ? 1 : 0);
+
+      parts.push(
+        `<rect x="${plot.left}" y="${barY.toFixed(1)}" width="${barWidth.toFixed(1)}" ` +
+          `height="${barHeight.toFixed(1)}" fill="${chartColor(theme, serieIndex, serie.color)}" rx="1.5" />`,
+      );
+
+      if (showValues && series.length === 1) {
+        parts.push(
+          text(valueFormat(raw), plot.left + barWidth + 4, barY + barHeight / 2 + 3, {
+            size: CHART_FONT.value,
+            fill: theme.mutedFg,
+          }),
+        );
+      }
+    });
+  });
+
+  return svgRoot(width, height, parts.join(''), options.ariaLabel);
+}

package/src/pdf/document/charts/chart-donut.ts

@@ -0,0 +1,163 @@
+import { SafeSvg } from '../pdf-document.types';
+import {
+  CHART_DEFAULT_HEIGHT,
+  CHART_FONT,
+  CHART_FULL_WIDTH,
+  ChartBaseOptions,
+  chartColor,
+  emptyChart,
+  svgRoot,
+  text,
+} from './chart-primitives';
+import { estimateTextWidth, formatNumber, truncateToWidth } from './chart-scale';
+
+export interface DonutSlice {
+  label: string;
+  value: number;
+  color?: string;
+}
+
+const polar = (cx: number, cy: number, radius: number, angle: number) => ({
+  x: cx + radius * Math.cos(angle),
+  y: cy + radius * Math.sin(angle),
+});
+
+/** Setor em anel, desenhado com dois arcos — o `path` é o único jeito no SVG puro. */
+function ringSegment(
+  cx: number,
+  cy: number,
+  outer: number,
+  inner: number,
+  start: number,
+  end: number,
+): string {
+  const largeArc = end - start > Math.PI ? 1 : 0;
+  const p1 = polar(cx, cy, outer, start);
+  const p2 = polar(cx, cy, outer, end);
+  const p3 = polar(cx, cy, inner, end);
+  const p4 = polar(cx, cy, inner, start);
+
+  if (inner <= 0) {
+    return (
+      `M${cx.toFixed(1)},${cy.toFixed(1)} L${p1.x.toFixed(1)},${p1.y.toFixed(1)} ` +
+      `A${outer},${outer} 0 ${largeArc} 1 ${p2.x.toFixed(1)},${p2.y.toFixed(1)} Z`
+    );
+  }
+
+  return (
+    `M${p1.x.toFixed(1)},${p1.y.toFixed(1)} A${outer},${outer} 0 ${largeArc} 1 ${p2.x.toFixed(1)},${p2.y.toFixed(1)} ` +
+    `L${p3.x.toFixed(1)},${p3.y.toFixed(1)} A${inner},${inner} 0 ${largeArc} 0 ${p4.x.toFixed(1)},${p4.y.toFixed(1)} Z`
+  );
+}
+
+/** Rosca (ou pizza, com `innerRadiusRatio: 0`) com legenda à direita. */
+export function donutChartSvg(
+  options: ChartBaseOptions & {
+    slices: DonutSlice[];
+    innerRadiusRatio?: number;
+    centerLabel?: string;
+    centerValue?: string;
+    showPercent?: boolean;
+  },
+): SafeSvg {
+  const {
+    theme,
+    slices,
+    width = CHART_FULL_WIDTH,
+    height = CHART_DEFAULT_HEIGHT,
+    innerRadiusRatio = 0.62,
+    showPercent = true,
+    valueFormat = (value: number) => formatNumber(value, 0),
+  } = options;
+
+  const usable = slices.filter((slice) => Number.isFinite(slice.value) && slice.value > 0);
+  const total = usable.reduce((sum, slice) => sum + slice.value, 0);
+
+  if (total <= 0) return emptyChart(options);
+
+  // A coluna da direita é dimensionada pelo texto que realmente vai nela: o
+  // valor ("318 · 76%") fixa a largura mínima, e o que sobra é do rótulo.
+  const valueLabels = usable.map((slice) =>
+    showPercent
+      ? `${valueFormat(slice.value)} · ${Math.round((slice.value / total) * 100)}%`
+      : valueFormat(slice.value),
+  );
+  const valueWidth = Math.max(
+    ...valueLabels.map((label) => estimateTextWidth(label, CHART_FONT.legend)),
+  );
+  // A largura do rótulo é decidida primeiro e a legenda é montada a partir dela.
+  // Derivar na ordem inversa (legenda menos valor menos folga) devolve o mesmo
+  // número com um epsilon de ponto flutuante a menos, e um rótulo que cabia
+  // certinho sai cortado — "Em risco" virava "Em ris…".
+  const maxLabelWidth = Math.min(
+    Math.max(...usable.map((s) => estimateTextWidth(s.label, CHART_FONT.legend))),
+    width * 0.45 - valueWidth - 26,
+  );
+  const legendWidth = maxLabelWidth + valueWidth + 26;
+  const chartWidth = width - legendWidth;
+  const radius = Math.min(chartWidth, height) / 2 - 8;
+  const cx = chartWidth / 2;
+  const cy = height / 2;
+  const inner = radius * innerRadiusRatio;
+
+  const parts: string[] = [];
+  // Começa às 12h: é onde o olho procura o início de uma rosca.
+  let angle = -Math.PI / 2;
+
+  usable.forEach((slice, index) => {
+    const sweep = (slice.value / total) * Math.PI * 2;
+    const color = chartColor(theme, index, slice.color);
+
+    parts.push(
+      `<path d="${ringSegment(cx, cy, radius, inner, angle, angle + sweep)}" fill="${color}" />`,
+    );
+    angle += sweep;
+  });
+
+  if (inner > 0 && (options.centerValue || options.centerLabel)) {
+    if (options.centerValue) {
+      parts.push(
+        text(options.centerValue, cx, cy + (options.centerLabel ? 0 : 4), {
+          size: 16,
+          fill: theme.ink,
+          anchor: 'middle',
+          weight: 700,
+        }),
+      );
+    }
+    if (options.centerLabel) {
+      parts.push(
+        text(options.centerLabel, cx, cy + 12, {
+          size: CHART_FONT.axis,
+          fill: theme.mutedFg,
+          anchor: 'middle',
+        }),
+      );
+    }
+  }
+
+  const legendX = chartWidth + 4;
+  const lineHeight = 15;
+  const legendTop = cy - (usable.length * lineHeight) / 2 + 8;
+
+  usable.forEach((slice, index) => {
+    const y = legendTop + index * lineHeight;
+    const label = truncateToWidth(
+      slice.label,
+      CHART_FONT.legend,
+      maxLabelWidth,
+    );
+
+    parts.push(
+      `<rect x="${legendX}" y="${y - 7}" width="8" height="8" rx="2" fill="${chartColor(theme, index, slice.color)}" />`,
+      text(label, legendX + 12, y, { size: CHART_FONT.legend, fill: theme.ink }),
+      text(valueLabels[index] ?? '', width, y, {
+        size: CHART_FONT.legend,
+        fill: theme.mutedFg,
+        anchor: 'end',
+      }),
+    );
+  });
+
+  return svgRoot(width, height, parts.join(''), options.ariaLabel);
+}