@luanpdd/kit-mcp 1.8.1 → 1.10.0

package/kit/agents/supabase-edge-fn-writer.md

@@ -178,8 +178,132 @@ Test local:
 - Função existente que precisa de pequeno ajuste → use Edit direto
 - Lógica que pode rodar em DB function (`security definer`) → considera `supabase-database-functions` (mais barato que Edge)
 
+## Observabilidade integrada
+
+Edge Function nasce instrumentada com OTel — não é addon. Beneficia mais que qualquer outro agent dado que é entry-point externo.
+
+1. **OTel SDK no topo do `index.ts`** (skill [`opentelemetry-standard`](../skills/opentelemetry-standard/SKILL.md)):
+   ```ts
+   import { trace } from 'npm:@opentelemetry/api@1.9.0'
+   import { NodeSDK } from 'npm:@opentelemetry/sdk-node@0.55.0'
+   import { OTLPTraceExporter } from 'npm:@opentelemetry/exporter-trace-otlp-http@0.55.0'
+   const sdk = new NodeSDK({ /* service.name, OTLP endpoint */ })
+   sdk.start()
+   ```
+2. **Span por handler** com kind `SERVER` envolvendo `Deno.serve`. Atributos canônicos: `request.id`, `user.id`, `tenant_id`, `endpoint`, `result.success`, `error.type`, `build_id` (`Deno.env.get('SUPABASE_GIT_SHA')`) — skill [`structured-events`](../skills/structured-events/SKILL.md).
+3. **Context propagation** via header `traceparent` para outbound calls a Postgres/PostgREST/external (skill [`distributed-tracing`](../skills/distributed-tracing/SKILL.md)).
+4. **Sampling head-based** baseado em `customer.tier` ou `feature_flag.<name>` (skill [`telemetry-sampling`](../skills/telemetry-sampling/SKILL.md) *Phase 34*) — 100% errors, 100% enterprise, 10% baseline.
+
+**Output adicionado:** template completo de Edge Function inclui SDK setup + span wrapper + propagação outbound + classificador de error.type. ODD-compliant (4 perguntas pré-PR endereçadas).
+
+## Four Golden Signals
+
+> Cross-ref canônico: [four-golden-signals](../skills/four-golden-signals/SKILL.md) (cap 6 do livro Google SRE — Monitoring Distributed Systems). Para retro-instrumentar Edge Function existente, delegar para [golden-signals-instrumenter](./golden-signals-instrumenter.md).
+
+Edge Function user-facing nasce com os 4 sinais dourados — não é addon. O bloco `## Observabilidade integrada` acima cobre OTel SDK + spans + propagation; este bloco especifica os **4 instrumentos canônicos** que o template gerado SEMPRE inclui:
+
+| Signal | Instrumento | Dimensão | Valor padrão |
+|---|---|---|---|
+| **Latency** | `meter.createHistogram('http_request_duration_ms')` com `explicitBucketBoundaries: [1,2,5,10,25,50,100,250,500,1000,2500,5000,10000,30000]` | `result=success\|error` (separar success de erro) | Bucketing exponencial captura long tail sem cardinality explosion |
+| **Traffic** | `meter.createCounter('http_requests_total')` | `endpoint`, `http_method` | Incrementado antes de processar request |
+| **Errors** | `meter.createCounter('http_errors_total')` | `error.type` enum (5-15 valores: `timeout\|validation\|auth\|rate_limit\|db\|provider_down\|...`) — **nunca** `error.message` (cardinalidade explode) | Incrementado em catch + path 4xx/5xx |
+| **Saturation** | `meter.createObservableGauge('saturation_pct')` com callback que lê estado real | resource-specific: `connection_pool` (pg) / `concurrency_limit` (Edge runtime) / `egress_bandwidth` / `cache_memory` | % do recurso mais escasso identificado ANTES de instrumentar |
+
+### Snippet canônico — adicionado ao topo do `index.ts` gerado
+
+```ts
+// PT-BR: 4 golden signals — instrumentação mínima universal
+import { metrics } from 'npm:@opentelemetry/api@1.9.0'
+const meter = metrics.getMeter('<function_name>')
+
+// 1. LATENCY — histogram bucketed exponencial
+const latencyHistogram = meter.createHistogram('http_request_duration_ms', {
+  description: 'Edge function latency split by result (success vs error)',
+  unit: 'ms',
+  advice: { explicitBucketBoundaries: [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000] }
+})
+
+// 2. TRAFFIC — counter de requests recebidos
+const trafficCounter = meter.createCounter('http_requests_total', {
+  description: 'Total HTTP requests received by edge function'
+})
+
+// 3. ERRORS — counter por error.type (NUNCA error.message — cardinalidade)
+const errorsCounter = meter.createCounter('http_errors_total', {
+  description: 'Edge function errors by error.type enum'
+})
+
+// 4. SATURATION — gauge do recurso mais escasso (callback lê estado real)
+// PT-BR: para Edge Function default, saturation = concurrency_limit_used %
+// Substituir callback conforme recurso identificado (db pool, queue, cache)
+meter.createObservableGauge('saturation_pct', {
+  description: 'Saturation of scarcest resource — function-specific'
+}).addCallback((result) => {
+  // PT-BR: callback canônico — ler estado real (ex: SELECT count(*) FROM pg_stat_activity)
+  // Aqui placeholder: 0 < value < 1
+  result.observe(getSaturationPct())  // implementar conforme resource
+})
+```
+
+### Wrapping no handler
+
+```ts
+Deno.serve(async (req: Request) => {
+  const start = performance.now()
+  const endpoint = new URL(req.url).pathname
+  trafficCounter.add(1, { endpoint, http_method: req.method })
+
+  try {
+    const response = await handle(req)
+    latencyHistogram.record(performance.now() - start, {
+      endpoint,
+      result: response.ok ? 'success' : 'error',
+    })
+    if (!response.ok) {
+      errorsCounter.add(1, { endpoint, 'error.type': classifyError(response) })
+    }
+    return response
+  } catch (err) {
+    latencyHistogram.record(performance.now() - start, { endpoint, result: 'error' })
+    errorsCounter.add(1, { endpoint, 'error.type': classifyError(err) })
+    throw err
+  }
+})
+
+// PT-BR: classifyError DEVE retornar enum fechado, não err.message
+function classifyError(e: unknown): string {
+  if (e instanceof TimeoutError) return 'timeout'
+  if (e instanceof ValidationError) return 'validation'
+  if (e instanceof AuthError) return 'auth'
+  // ... 5-15 valores no total
+  return 'unknown'
+}
+```
+
+### Saturation por tipo de Edge Function
+
+| Tipo de função | Recurso mais escasso | Implementação típica |
+|---|---|---|
+| API simples (GET/POST com leitura DB) | `pg_pool` connections used | `select count(*) from pg_stat_activity where state = 'active'` |
+| RAG / embeddings | `concurrency_limit` (provider externo) | counter de requests in-flight |
+| Email / queue consumer (cron → pgmq) | `pgmq.queue_length` | `select msg_count from pgmq.metrics_<queue>` |
+| Storage I/O heavy (uploads grandes) | `egress_bandwidth` | bytes-out tracker em window |
+
+### Anti-patterns prevenidos
+
+- Errors counter usando `error.type = err.message` → SEMPRE enum fechado (5-15 valores)
+- Latency mistura success + error → SEMPRE `result` dimension separa
+- Mean latency em vez de histogram → SEMPRE histogram com percentis derivados em backend
+- Saturation genérico (CPU%) sem identificar recurso real → SEMPRE escolher recurso scarcest da função
+
 ## Ver também
 
 - [supabase-edge-functions](../skills/supabase-edge-functions/SKILL.md) — base de conhecimento canônica
 - [supabase-cron-queues](../skills/supabase-cron-queues/SKILL.md) — pattern `cron → pgmq → Edge Function`
 - [supabase-auth-ssr](../skills/supabase-auth-ssr/SKILL.md) — clients Supabase
+- [opentelemetry-standard](../skills/opentelemetry-standard/SKILL.md) — SDK setup para Deno
+- [distributed-tracing](../skills/distributed-tracing/SKILL.md) — context propagation
+- [structured-events](../skills/structured-events/SKILL.md) — campos canônicos
+- [observability-driven-development](../skills/observability-driven-development/SKILL.md) — 4 perguntas pré-PR
+- [four-golden-signals](../skills/four-golden-signals/SKILL.md) — 4 sinais canônicos (Latency, Traffic, Errors, Saturation) cap 6 livro Google SRE
+- [golden-signals-instrumenter](./golden-signals-instrumenter.md) — agent que retro-instrumenta Edge Functions existentes com os 4 signals

package/kit/agents/supabase-migration-writer.md

@@ -154,3 +154,101 @@ Próximos passos:
 - `auth.uid()` sem `(select)` → SEMPRE wrapper
 - Schema-qualifier ausente em DB functions → SEMPRE `public.<name>`
 - Comandos destrutivos sem comentário → BLOQUEIA até user adicionar Risk/Validation/Rollback
+
+## Observabilidade integrada
+
+Toda migration emite evento estruturado e cria audit hooks por default — não é addon, é parte do contrato (skill [`observability-driven-development`](../skills/observability-driven-development/SKILL.md)).
+
+1. **Migration event** (auto-gerado no fim da migration):
+   ```sql
+   -- PT-BR: emite linha em observability.migration_events
+   insert into observability.migration_events (
+     migration_id, sql_hash, applied_at, build_id, result_success, duration_ms
+   ) values (
+     '20260506120000_create_orders', md5(...), now(), '{{BUILD_ID}}', true, {{ELAPSED_MS}}
+   );
+   ```
+2. **Audit triggers em tabelas sensíveis** (pagamentos, auth, dados pessoais): trigger `after insert/update/delete` que insere `audit_log` com `tenant_id`, `user_id`, `op`, `old_row`, `new_row`, `actor`, `timestamp`.
+3. **Atributos canônicos** em qualquer função criada: `set search_path = ''` + comments com `result.success`, `error.type` enum esperado (skill [`structured-events`](../skills/structured-events/SKILL.md)).
+
+**Output adicionado:** seção "## Audit hooks" + "## Migration event emit" no SQL gerado, comentadas em PT-BR.
+
+## Alerta toil — automação via pg_cron
+
+> Cross-ref canônico: [eliminating-toil](../skills/eliminating-toil/SKILL.md) (cap 5 do livro Google SRE — Eliminating Toil). Para auditoria sistemática de toil em todo o repo, delegar para [toil-auditor](./toil-auditor.md).
+
+Migrations SQL executadas **manualmente em cadência regular** (rebuild índice, VACUUM, REFRESH MATERIALIZED VIEW, ANALYZE) são toil canônico — passam todos os 6 critérios: manual, repetitivo, automatizável, tático, sem valor durável, escala linear. Este agent **detecta padrões de toil** ao escrever migration e **alerta proativamente** sugerindo automação via `pg_cron`.
+
+### 6 critérios — quando uma migration é toil-prone
+
+Migration descreve operação que será re-executada > 1× = toil-prone. Aplicar 6 critérios da skill `eliminating-toil`:
+
+| Critério | Pergunta | Sinal de toil |
+|---|---|---|
+| 1. Manual | Operador roda `psql` ou aplica migration "quando lembra"? | Sim |
+| 2. Repetitivo | Já foi executada 3+ vezes em milestones diferentes? | Sim |
+| 3. Automatizável | `pg_cron` consegue agendar sem julgamento humano? | Sim |
+| 4. Tático | Reage a sintoma (lentidão, bloat, stale view) sem planejar? | Sim |
+| 5. Sem valor durável | Não cria asset permanente — só "limpa" estado | Sim |
+| 6. Escala linear | Mais users / mais dados = mais frequência manual | Sim |
+
+Se TODOS os 6 = sim → **toil**. Bloquear migration manual recorrente; oferecer alternativa via `pg_cron`.
+
+### Padrões SQL canônicos que SEMPRE disparam alerta toil
+
+| Operação manual | Por quê é toil | Automação canônica |
+|---|---|---|
+| `REINDEX TABLE x` recorrente (a cada N semanas) | Rebuild de bloat de índice é tático, sem valor durável, repetitivo | `select cron.schedule('reindex_x', '0 3 * * 0', $$reindex table x$$);` (semanal 3am) |
+| `VACUUM ANALYZE x` manual | autovacuum não está acompanhando — sintoma de tuning, não fix manual | Tunar `autovacuum_vacuum_scale_factor` para tabela específica + `pg_cron` se necessário |
+| `REFRESH MATERIALIZED VIEW x` manual | Stale view detectada por user reclamação ou alert | `select cron.schedule('refresh_x', '*/30 * * * * *', $$refresh materialized view concurrently x$$);` |
+| `ANALYZE` em tabela após bulk insert manual | Estatísticas desatualizadas após ETL — bem conhecido | Trigger AFTER INSERT/COPY com `analyze` no fim do batch, ou `pg_cron` pós-ETL |
+| `delete from logs where created_at < now() - interval '90d'` manual recorrente | Retention manual = toil clássico | `select cron.schedule('purge_logs', '0 4 * * *', $$delete from logs where ...$$);` |
+| `dump + restore` periódico para estatísticas / planos cache | Operação repetitiva sem valor permanente | `pg_cron` job ou `pg_stat_reset_*()` calls automatizadas |
+
+### Snippet canônico — converter manual em pg_cron
+
+```sql
+-- PT-BR: ANTES — toil (operador roda manualmente)
+-- $ psql -c 'reindex table heavy_table;'   ← repetir a cada 2 semanas
+
+-- PT-BR: DEPOIS — automação via pg_cron (necessita extension pg_cron habilitada)
+create extension if not exists pg_cron;
+
+select cron.schedule(
+  'reindex_heavy_table_biweekly',
+  '0 3 1,15 * *',                            -- 3am dias 1 e 15
+  $$ reindex table public.heavy_table $$
+);
+
+-- PT-BR: monitor — falha em job pg_cron emite linha em cron.job_run_details
+-- alimentar alerta SLO se job falha 3+ vezes seguidas
+```
+
+### Quando NÃO automatizar (não é toil)
+
+- **Migration de schema (DDL one-shot)** — `create table`, `alter table add column` são project work, não toil. Não recorrentes.
+- **Backfill data único** — `update orders set status = ...` aplicado 1× para corrigir bug é grungy work, não toil.
+- **Rebuild que requer julgamento** — `reindex` que requer escolher hora baseada em load patterns variáveis, ou que precisa coordenação com release. Mantém manual mas documenta runbook.
+
+### Output do agent — adicionado ao SQL gerado
+
+Quando o agent detecta que a migration descreve operação toil-prone (regex em DDL: `reindex|vacuum|refresh materialized|delete from .* interval`), adiciona comentário-alerta no header do arquivo SQL gerado:
+
+```sql
+/*
+  ⚠ TOIL ALERT — esta operação parece recorrente.
+  
+  Se será executada em cadência regular, considere automação via pg_cron:
+    select cron.schedule('<job_name>', '<schedule>', $$ <sql> $$);
+  
+  Cross-ref: kit/skills/eliminating-toil/SKILL.md (6 critérios canônicos)
+             kit/agents/toil-auditor.md (audit sistemático para repo todo)
+*/
+```
+
+### Anti-patterns prevenidos
+
+- "Roda quando der" runbook → SEMPRE pg_cron + monitoring de falha do job
+- `pg_cron` schedule mas sem alerta de falha → SEMPRE incluir SLO em `cron.job_run_details` (% sucesso 30d)
+- Automação parcial (script humano-iniciado) → ainda é toil (humano pressiona botão); preferir cron.schedule completo
+- Migration manual recorrente "porque é só uma vez por mês" → 12×/ano = toil, regra ≤ 50% se acumular vários "só um por mês"

package/kit/agents/supabase-realtime-implementer.md

@@ -245,8 +245,31 @@ PRÓXIMOS PASSOS
 - Presence para listas de objetos → ALERTA explícito (use queries normais)
 - Naming inconsistente → SEMPRE `scope:entity:id`
 
+## Observabilidade integrada
+
+Realtime é tipicamente fora-de-trace porque WebSocket não usa header `traceparent` por default. Patches:
+
+1. **Trace context no payload do broadcast** (skill [`distributed-tracing`](../skills/distributed-tracing/SKILL.md)):
+   ```ts
+   // PT-BR: producer — anexa traceparent ao payload do broadcast
+   const carrier: Record<string, string> = {}
+   propagation.inject(context.active(), carrier)
+   await channel.send({
+     type: 'broadcast',
+     event: 'message_inserted',
+     payload: { ...originalPayload, _trace_context: carrier }
+   })
+   ```
+2. **Consumer extrai contexto** ao receber broadcast e abre span filho — stitching cross-WebSocket fica completo.
+3. **Atributos canônicos** em todo span de subscribe/unsubscribe (skill [`structured-events`](../skills/structured-events/SKILL.md)): `channel.name`, `channel.private`, `subscribe.status` (`SUBSCRIBED` | `CHANNEL_ERROR` | `TIMED_OUT`), `user.id`, `tenant_id`.
+4. **Trigger DB** (`realtime.broadcast_changes`) emite evento estruturado em `observability.events` com `event_name = 'realtime_broadcast'`, `result_success`, `tenant_id`.
+
+**Output adicionado:** template inclui propagation.inject no payload + span wrapper em subscribe + atributos canônicos no callback.
+
 ## Ver também
 
 - [supabase-realtime](../skills/supabase-realtime/SKILL.md) — base de conhecimento canônica
 - [supabase-rls-writer](./supabase-rls-writer.md) — invocar para policies adicionais em tabelas do app
 - [supabase-database-functions](../skills/supabase-database-functions/SKILL.md) — trigger function pattern
+- [distributed-tracing](../skills/distributed-tracing/SKILL.md) — context propagation cross-WebSocket
+- [structured-events](../skills/structured-events/SKILL.md) — atributos canônicos para channels

package/kit/agents/supabase-rls-writer.md

@@ -212,7 +212,24 @@ NOTAS
 - Tabela já tem policies estabelecidas e user só quer 1 ajuste pequeno → use Edit direto
 - Tabela é puramente read-only para `anon` (ex: catalog público) → policy trivial, overhead
 
+## Observabilidade integrada
+
+RLS denials são sinal de segurança e debug — emite evento estruturado SEMPRE.
+
+1. **RLS deny logging**: no entry-point do app (Edge Function ou backend), capturar `42501 insufficient_privilege` errors e emitir span com:
+   - `policy.name` (qual policy negou)
+   - `attempted_op` (`select` | `insert` | `update` | `delete`)
+   - `user.id` (de `auth.uid()` na sessão)
+   - `tenant_id` (de `app_metadata` quando aplicável)
+   - `resource.table` (qual tabela/view tentada)
+   - `error.type = 'authz'` (skill [`structured-events`](../skills/structured-events/SKILL.md))
+2. **Investigação via Core Analysis Loop** (skill [`core-analysis-loop`](../skills/core-analysis-loop/SKILL.md)): pergunta canônica "qual policy + qual tenant + qual op + quando começou?" → query agrupando por essas 4 dimensões para identificar pattern.
+
+**Output adicionado:** seção "## Observability hooks" com snippet de error handler que classifica RLS denial e emite span.
+
 ## Ver também
 
 - [supabase-rls-policies](../skills/supabase-rls-policies/SKILL.md) — base de conhecimento canônica das regras
 - [supabase-migration-writer](./supabase-migration-writer.md) — invocar quando user quer policies dentro de migration nova
+- [structured-events](../skills/structured-events/SKILL.md) — campos canônicos para RLS denial logging
+- [core-analysis-loop](../skills/core-analysis-loop/SKILL.md) — investigar denial patterns

package/kit/agents/supabase-storage-implementer.md

@@ -233,8 +233,182 @@ ALERTAS
 - **Vector Buckets / Analytics Buckets** ainda alpha em 2026-05-06 — não detalhar
 - **Smart CDN** para egress optimization — fora deste agent (config no Dashboard)
 
+## Observabilidade integrada
+
+Upload events são quentes em custo (egress + storage) e em UX (lentidão de upload = abandono). Instrumentar SEMPRE.
+
+1. **Span por upload/download** (skill [`structured-events`](../skills/structured-events/SKILL.md)) com atributos:
+   - `bucket.name`, `bucket.public` (bool)
+   - `file.size_bytes`, `file.mime_type`, `file.path`
+   - `operation`: `upload` | `download` | `signed_url` | `delete`
+   - `result.success`, `error.type` (enum: `quota_exceeded`, `unauthorized`, `mime_blocked`, `size_exceeded`, `network`)
+   - `duration_ms`, `transfer.bytes_per_second` (calculado)
+   - `user.id`, `tenant_id` (do `auth.uid()`)
+2. **Sampling** (skill [`telemetry-sampling`](../skills/telemetry-sampling/SKILL.md) *Phase 34*): 100% errors, 100% uploads > 10 MB (cardinalidade baixa, valor alto), 5% baseline para downloads pequenos (alto volume).
+3. **Audit log** para uploads em buckets sensíveis (`audit_log` table com `actor`, `op`, `resource`, `geo`, `user_agent`).
+
+**Output adicionado:** seção "## Observability hooks" com snippet de upload/download wrapper.
+
+## Saturation signal — bucket size + quota
+
+> Cross-ref canônico: [four-golden-signals](../skills/four-golden-signals/SKILL.md) (cap 6 do livro Google SRE — Monitoring Distributed Systems). Para retro-instrumentar storage existente com os 4 signals, delegar para [golden-signals-instrumenter](./golden-signals-instrumenter.md).
+
+Storage tem o **recurso mais escasso explícito**: o quota do plano (Free 1 GB, Pro 100 GB, Team 1 TB, etc.). Sem signal de saturation, time descobre quota exhaustion via incident (uploads falham silenciosamente em UX) — **anti-pattern clássico** de white-box monitoring sem detecção precoce. O bloco `## Observabilidade integrada` acima cobre Latency / Traffic / Errors (3 signals); este bloco completa com **Saturation** — o 4º signal canônico.
+
+### Saturation = bucket size ÷ quota plan
+
+| Plano | Quota total | Threshold ALERT (yellow) | Threshold PAGE (red) |
+|---|---|---|---|
+| Free | 1 GB | 80% (800 MB) | 95% (950 MB) |
+| Pro | 100 GB | 80% (80 GB) | 95% (95 GB) |
+| Team | 1 TB | 80% (800 GB) | 95% (950 GB) |
+| Enterprise | custom | custom | custom |
+
+### Signal 1 — Gauge: bucket size atual (bytes)
+
+`ObservableGauge` (push periódico via callback) mede tamanho real de cada bucket. Callback consulta `storage.objects` agregado:
+
+```ts
+// PT-BR: 4º signal — saturation (gauge de bucket size em bytes)
+import { metrics } from 'npm:@opentelemetry/api@1.9.0'
+const meter = metrics.getMeter('supabase-storage')
+
+meter.createObservableGauge('storage_bucket_bytes', {
+  description: 'Tamanho atual em bytes por bucket — saturation signal',
+  unit: 'bytes',
+}).addCallback(async (result) => {
+  // PT-BR: query agregada (rodar via service-role client em cron)
+  const sizes = await supabaseAdmin.rpc('storage_bucket_sizes_bytes')
+  // expected: [{ bucket_id: 'avatars', total_bytes: 12345678 }, ...]
+  for (const row of sizes ?? []) {
+    result.observe(row.total_bytes, { 'bucket.id': row.bucket_id })
+  }
+})
+
+meter.createObservableGauge('storage_saturation_pct', {
+  description: 'Saturation = bucket size / quota plan — % do quota usado',
+  unit: '1',  // ratio (0..1)
+}).addCallback(async (result) => {
+  const sizes = await supabaseAdmin.rpc('storage_bucket_sizes_bytes')
+  const QUOTA_BYTES = Number(Deno.env.get('SUPABASE_PLAN_QUOTA_BYTES') ?? 1_000_000_000)  // default Free
+  for (const row of sizes ?? []) {
+    result.observe(row.total_bytes / QUOTA_BYTES, { 'bucket.id': row.bucket_id })
+  }
+})
+```
+
+SQL helper para o callback:
+
+```sql
+-- PT-BR: function que retorna bytes por bucket — chamada por callback OTel
+create or replace function public.storage_bucket_sizes_bytes()
+returns table (bucket_id text, total_bytes bigint)
+language sql
+security definer
+set search_path = ''
+as $$
+  select bucket_id, coalesce(sum((metadata->>'size')::bigint), 0) as total_bytes
+  from storage.objects
+  group by bucket_id;
+$$;
+```
+
+### Signal 2 — Counter: quota near-exhaustion events
+
+`Counter` incrementa a cada upload que **detecta** approach a quota threshold (80%, 95%). Permite contar eventos críticos para alerting:
+
+```ts
+// PT-BR: counter incrementado em cada upload
+const quotaWarnings = meter.createCounter('storage_quota_warnings_total', {
+  description: 'Counter de eventos onde upload aproxima quota — alimentar alert SLO',
+})
+
+export async function uploadInstrumented(file: File, filename: string) {
+  const supabase = createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) throw new Error('not authenticated')
+
+  const path = `${user.id}/${filename}`
+
+  // PT-BR: pre-check — saturation atual antes de upload
+  const sizes = await supabaseAdmin.rpc('storage_bucket_sizes_bytes')
+  const bucketSize = sizes?.find(s => s.bucket_id === '<bucket_name>')?.total_bytes ?? 0
+  const QUOTA = Number(Deno.env.get('SUPABASE_PLAN_QUOTA_BYTES') ?? 1_000_000_000)
+  const saturation = bucketSize / QUOTA
+
+  if (saturation >= 0.95) {
+    quotaWarnings.add(1, { 'bucket.id': '<bucket_name>', threshold: '95pct' })
+  } else if (saturation >= 0.80) {
+    quotaWarnings.add(1, { 'bucket.id': '<bucket_name>', threshold: '80pct' })
+  }
+
+  const { data, error } = await supabase.storage
+    .from('<bucket_name>')
+    .upload(path, file, { upsert: true })
+
+  if (error) throw error
+  return data.path
+}
+```
+
+### Cron schedule sugerido
+
+Saturation gauge não precisa rodar em cada request — agendar leitura via `pg_cron` (ou OTel SDK polling interval = 60s) é suficiente:
+
+```sql
+-- PT-BR: refresh saturation cache a cada 60s para gauge OTel
+create materialized view if not exists obs.storage_saturation as
+  select bucket_id, sum((metadata->>'size')::bigint) as total_bytes, now() as captured_at
+  from storage.objects
+  group by bucket_id;
+
+select cron.schedule(
+  'refresh_storage_saturation',
+  '* * * * *',  -- a cada 1 min
+  $$ refresh materialized view concurrently obs.storage_saturation $$
+);
+```
+
+### Alert SLO sobre saturation
+
+Saturation alimenta SLO event-based — não threshold direto:
+
+```yaml
+# PT-BR: SLO sobre quota — % de tempo em yellow ou worse
+slo:
+  name: storage_quota_healthy
+  target: 0.99            # 99% do tempo em < 80% quota
+  window: 30d_sliding
+  sli:
+    type: event_based
+    good_event:
+      saturation_pct: { lt: 0.80 }
+    bad_event:
+      saturation_pct: { gte: 0.80 }
+```
+
+### Output do agent — adicionado ao SQL/código gerado
+
+Quando agent gera bucket privado novo, **sempre inclui**:
+1. Function SQL `storage_bucket_sizes_bytes()` (uma vez por projeto)
+2. Materialized view `obs.storage_saturation` + pg_cron refresh job
+3. Snippet OTel ObservableGauge no código client wrapper
+4. Counter `storage_quota_warnings_total` no upload wrapper
+5. SLO `storage_quota_healthy` em `.planning/slos/<bucket>.yaml`
+
+### Anti-patterns prevenidos
+
+- Saturation = "% disco do servidor" → SEMPRE saturation = % quota plan (recurso correto)
+- Threshold direto em alerta CPU/memory para capacity → SEMPRE SLO event-based sobre saturation_pct
+- Polling de bucket size em cada request → SEMPRE materialized view + pg_cron refresh + OTel polling 60s
+- Plan quota hardcoded → SEMPRE env var `SUPABASE_PLAN_QUOTA_BYTES` (varia por plano, pode ser sobrescrita em test)
+
 ## Ver também
 
 - [supabase-storage](../skills/supabase-storage/SKILL.md) — base de conhecimento canônica
 - [supabase-rls-writer](./supabase-rls-writer.md) — invocar para policies adicionais
 - [supabase-auth-ssr](../skills/supabase-auth-ssr/SKILL.md) — usuário autenticado obtém `auth.uid()`
+- [structured-events](../skills/structured-events/SKILL.md) — campos canônicos para upload/download events
+- [telemetry-sampling](../skills/telemetry-sampling/SKILL.md) *(Phase 34)* — head-based sampling por size_bytes
+- [four-golden-signals](../skills/four-golden-signals/SKILL.md) — 4 sinais canônicos (Latency, Traffic, Errors, Saturation) cap 6 livro Google SRE — saturation = bucket size / quota plan
+- [golden-signals-instrumenter](./golden-signals-instrumenter.md) — agent que retro-instrumenta storage existente com os 4 signals