Anos disponíveis e frescor dos cubos

Previous value: -"Bloco de proveniência (contrato v1.1): fonte, URL, competência, extração, diagnóstico de origem, citação e licença"New value: +"Bloco de proveniência do portfólio: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, avisos, o que o servidor calculou e se o número ainda pode mudar"

Added value: +{
+  "description": "Como o número foi calculado; presente junto com derived",
+  "type": "string"
+}

Added value: +{
+  "description": "Presente (true) quando o número foi calculado por este servidor — os cubos SIH são somas das internações dos arquivos do DATASUS",
+  "type": "boolean"
+}

Added value: +{
+  "description": "Avisos que acompanham o dado (ex.: cubo atrás do espelho healthbr-data, frescor não verificado). Ausente quando não há aviso",
+  "items": {
+    "type": "string"
+  },
+  "minItems": 1,
+  "type": "array"
+}

Previous value: -"Diagnóstico de origem desta chamada (contrato v1.1): idas ao canal sih/cubos/ do healthbr-data (manifesto e arquivos que faltavam no disco), tentativas somadas e anomalias contornadas; unstable=true quando houve anomalia. null = a resposta veio do DISCO (cache aquecido) ou o bloco não é do canal (listas de referência)"New value: +"Diagnóstico de origem desta chamada: idas ao canal sih/cubos/ do healthbr-data (manifesto e arquivos que faltavam no disco), tentativas somadas e anomalias contornadas; unstable=true quando houve anomalia. null = a resposta veio do DISCO (cache aquecido) ou o bloco não é do canal (listas de referência)"

Added value: +{
+  "additionalProperties": false,
+  "description": "Se o número ainda pode mudar: provisional quando algum ano da resposta ainda tem competências abertas no SIH (o total ainda pode crescer); current nos demais — o DATASUS reedita arquivos de competências passadas",
+  "properties": {
+    "note": {
+      "description": "O específico da fonte: o que revisa, quando, por quê",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "status": {
+      "description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte",
+      "enum": [
+        "current",
+        "provisional",
+        "final"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "note"
+  ],
+  "type": "object"
+}

Added value: +{
+  "description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só",
+  "items": {
+    "additionalProperties": false,
+    "description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
+    "properties": {
+      "data_vintage": {
+        "description": "Vintage/competência da sub-fonte",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "dataset_id": {
+        "description": "Identificador do conjunto da sub-fonte",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "fields": {
+        "description": "Campos do payload atribuídos a esta sub-fonte",
+        "items": {
+          "type": "string"
+        },
+        "minItems": 1,
+        "type": "array"
+      },
+      "retrieved_at": {
+        "description": "ISO-8601 da extração desta sub-fonte na origem",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "served_from_cache": {
+        "description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "source_url": {
+        "description": "URL canônica da sub-fonte que originou estes campos",
+        "type": "string"
+      }
+    },
+    "required": [
+      "fields",
+      "source_url",
+      "dataset_id",
+      "data_vintage",
+      "retrieved_at"
+    ],
+    "type": "object"
+  },
+  "minItems": 1,
+  "type": "array"
+}

Previous value: -"Instante REAL da extração na origem (ISO-8601) — para os cubos SIH, a safra do sidecar (extração no FTP do DATASUS), nunca o instante do download"New value: +"Instante REAL da extração na origem (ISO-8601) — para os cubos SIH, o download MAIS ANTIGO, do FTP do DATASUS, entre os .dbc que alimentaram a resposta (cópia idêntica ao original naquela data, MD5 registrado no sidecar), nunca o instante da chamada"

Previous value: -"Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença"New value: +"Bloco de proveniência (contrato v1.1): fonte, URL, competência, extração, diagnóstico de origem, citação e licença"

Added value: +{
+  "description": "Diagnóstico de origem desta chamada (contrato v1.1): idas ao canal sih/cubos/ do healthbr-data (manifesto e arquivos que faltavam no disco), tentativas somadas e anomalias contornadas; unstable=true quando houve anomalia. null = a resposta veio do DISCO (cache aquecido) ou o bloco não é do canal (listas de referência)",
+  "oneOf": [
+    {
+      "additionalProperties": false,
+      "description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
+      "properties": {
+        "anomalies": {
+          "description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "count": {
+                "description": "Ocorrências desta classe na chamada",
+                "minimum": 1,
+                "type": "integer"
+              },
+              "kind": {
+                "description": "Classe da anomalia (vocabulário fechado do contrato)",
+                "enum": [
+                  "timeout",
+                  "network",
+                  "http_4xx",
+                  "http_5xx",
+                  "rate_limited",
+                  "malformed_body"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "kind",
+              "count"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "attempts": {
+          "description": "Tentativas somadas, incluindo as repetidas (>= requests)",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "requests": {
+          "description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "unstable": {
+          "description": "true se houve repetição (attempts > requests) ou alguma anomalia",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "requests",
+        "attempts",
+        "anomalies",
+        "unstable"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

Previous value: -"Instante REAL da extração na origem (ISO-8601)"New value: +"Instante REAL da extração na origem (ISO-8601) — para os cubos SIH, a safra do sidecar (extração no FTP do DATASUS), nunca o instante do download"

Previous value: -[
-  "source",
-  "source_url",
-  "data_vintage",
-  "retrieved_at",
-  "citation",
-  "license"
-]New value: +[
+  "source",
+  "source_url",
+  "data_vintage",
+  "retrieved_at",
+  "retrieval",
+  "citation",
+  "license"
+]

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "anyOf": [
+    {
+      "required": [
+        "years",
+        "data_range",
+        "note",
+        "race_available",
+        "years_without_race",
+        "cid_revision",
+        "years_cid9",
+        "icsap_available",
+        "icsap_list_revision",
+        "uf_basis",
+        "years_uf_arquivo",
+        "municipality_available",
+        "currency",
+        "records_date_imputed",
+        "csap_universe",
+        "population_years",
+        "cubes_channel",
+        "freshness"
+      ]
+    },
+    {
+      "required": [
+        "error",
+        "years"
+      ]
+    }
+  ],
+  "description": "Anos com cubo local, o que cada ano carrega (revisão da CID, raça/cor, município, moeda, universo ICSAP), cobertura da população, canal de cubos e frescor",
+  "properties": {
+    "attribution": {
+      "description": "URLs canônicas das fontes desta resposta (lista de atribuição)",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "cid_revision": {
+      "additionalProperties": {
+        "additionalProperties": {
+          "description": "Internações naquela revisão; null quando o sidecar não traz o total",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "description": "Revisão da CID (\"9\" ou \"10\") → internações",
+        "type": "object"
+      },
+      "description": "Internações por revisão da CID — chave é o ano (string)",
+      "type": "object"
+    },
+    "csap_universe": {
+      "additionalProperties": {
+        "additionalProperties": false,
+        "description": "Universo do % ICSAP como o csapAIH; null em cubo anterior ao builder 2.6.0",
+        "properties": {
+          "excluded": {
+            "additionalProperties": {
+              "description": "Internações fora do universo por este motivo",
+              "type": "number"
+            },
+            "description": "Motivo de exclusão → internações",
+            "type": "object"
+          },
+          "method": {
+            "description": "Método (csapAIH)",
+            "type": "string"
+          },
+          "records_in_universe": {
+            "description": "Internações dentro do universo",
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "method",
+          "records_in_universe",
+          "excluded"
+        ],
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "description": "Universo do % ICSAP — chave é o ano (string)",
+      "type": "object"
+    },
+    "cubes_channel": {
+      "additionalProperties": false,
+      "description": "Canal público dos cubos e cache local",
+      "properties": {
+        "base_url": {
+          "description": "URL do canal público de cubos",
+          "type": "string"
+        },
+        "cache_dir": {
+          "description": "Pasta do cache local; null quando desligado",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "enabled": {
+          "description": "false quando o cache de cubos está desligado",
+          "type": "boolean"
+        },
+        "manifest_generated_at": {
+          "description": "Quando o manifesto foi gerado; null sem manifesto",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "manifest_source": {
+          "description": "De onde veio o manifesto",
+          "enum": [
+            "remote",
+            "disk",
+            "none",
+            "disabled"
+          ]
+        },
+        "note": {
+          "description": "Como o cache baixa os anos pedidos",
+          "type": "string"
+        },
+        "published_years": {
+          "description": "Anos publicados no manifesto do canal",
+          "items": {
+            "type": "number"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "enabled",
+        "base_url",
+        "published_years",
+        "cache_dir",
+        "manifest_source"
+      ],
+      "type": "object"
+    },
+    "currency": {
+      "additionalProperties": {
+        "description": "Moeda de `value` por competência; null quando o sidecar não informa",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "code": {
+              "description": "Código ISO 4217 (BRE, BRR, BRL)",
+              "type": "string"
+            },
+            "from": {
+              "description": "Primeira competência (AAAA-MM)",
+              "type": "string"
+            },
+            "name": {
+              "description": "Nome da moeda",
+              "type": "string"
+            },
+            "symbol": {
+              "description": "Símbolo (Cr$, CR$, R$)",
+              "type": "string"
+            },
+            "to": {
+              "description": "Última competência (AAAA-MM)",
+              "type": "string"
+            }
+          },
+          "required": [
+            "from",
+            "to",
+            "code",
+            "symbol",
+            "name"
+          ],
+          "type": "object"
+        },
+        "type": [
+          "array",
+          "null"
+        ]
+      },
+      "description": "Moeda de `value` — chave é o ano (string)",
+      "type": "object"
+    },
+    "data_range": {
+      "additionalProperties": false,
+      "description": "Intervalo dos anos locais",
+      "properties": {
+        "first_year": {
+          "description": "Primeiro ano local; ausente quando não há cubo",
+          "type": "number"
+        },
+        "last_year": {
+          "description": "Último ano local; ausente quando não há cubo",
+          "type": "number"
+        },
+        "total_years": {
+          "description": "Quantos anos",
+          "type": "number"
+        }
+      },
+      "required": [
+        "total_years"
+      ],
+      "type": "object"
+    },
+    "error": {
+      "description": "Falha ao listar os anos",
+      "type": "string"
+    },
+    "freshness": {
+      "additionalProperties": false,
+      "description": "Frescor dos cubos locais frente ao espelho healthbr-data",
+      "properties": {
+        "checked_at": {
+          "description": "Instante (UTC) da última checagem; null se nunca terminou",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "cubes": {
+          "description": "Cubos atrasados frente ao espelho",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "behind": {
+                "description": "true quando alguma lista acima tem item",
+                "type": "boolean"
+              },
+              "cube_year": {
+                "description": "Ano do cubo",
+                "type": "number"
+              },
+              "new_in_window": {
+                "description": "Competências publicadas depois do build",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "reedited": {
+                "description": "Partições cujo .dbc de origem mudou (reedição do MS)",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "removed": {
+                "description": "Partições que saíram do manifesto",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "reprocessed": {
+                "description": "Partições regeneradas pelo espelho",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              }
+            },
+            "required": [
+              "cube_year",
+              "reedited",
+              "reprocessed",
+              "removed",
+              "new_in_window",
+              "behind"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "error": {
+          "description": "Erro da checagem; null quando não houve",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "manifest_last_updated_local": {
+          "description": "Manifesto com que os cubos foram gerados",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "manifest_last_updated_remote": {
+          "description": "Manifesto público lido agora",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "manifest_url": {
+          "description": "URL do manifesto do espelho",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "method": {
+          "description": "Como checou: sonda parcial ou manifesto inteiro",
+          "enum": [
+            "range",
+            "full",
+            null
+          ]
+        },
+        "status": {
+          "description": "Frescor dos cubos frente ao espelho",
+          "enum": [
+            "disabled",
+            "pending",
+            "current",
+            "stale",
+            "unknown"
+          ]
+        }
+      },
+      "required": [
+        "status",
+        "checked_at",
+        "method",
+        "manifest_url",
+        "manifest_last_updated_local",
+        "manifest_last_updated_remote",
+        "cubes",
+        "error"
+      ],
+      "type": "object"
+    },
+    "icsap_available": {
+      "additionalProperties": {
+        "description": "true quando o cubo tem a marcação ICSAP",
+        "type": "boolean"
+      },
+      "description": "ICSAP disponível — chave é o ano (string)",
+      "type": "object"
+    },
+    "icsap_list_revision": {
+      "additionalProperties": {
+        "additionalProperties": {
+          "description": "Lista usada (portaria-221-2008 ou cid9-derivada)",
+          "type": "string"
+        },
+        "description": "Revisão → lista",
+        "type": "object"
+      },
+      "description": "Lista ICSAP por revisão da CID — chave é o ano (string)",
+      "type": "object"
+    },
+    "municipality_available": {
+      "additionalProperties": {
+        "description": "false quando `municipality_code` é nulo em todas as linhas",
+        "type": "boolean"
+      },
+      "description": "Município disponível — chave é o ano (string)",
+      "type": "object"
+    },
+    "note": {
+      "description": "Aviso sobre o que `years` significa",
+      "type": "string"
+    },
+    "population_years": {
+      "additionalProperties": false,
+      "description": "Cobertura dos arquivos de população por UF: o que as ferramentas de taxa aceitam",
+      "properties": {
+        "aggregated": {
+          "additionalProperties": false,
+          "description": "pop_uf_agregado.parquet — faixa etária quinquenal por UF e sexo (1991–1999)",
+          "properties": {
+            "age": {
+              "description": "Grão etário do arquivo",
+              "type": "string"
+            },
+            "age_groups": {
+              "description": "Faixas etárias quinquenais (só no arquivo agregado)",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "first_year": {
+              "description": "Primeiro ano coberto",
+              "type": "number"
+            },
+            "last_year": {
+              "description": "Último ano coberto",
+              "type": "number"
+            },
+            "source": {
+              "description": "Arquivo parquet que serve o intervalo",
+              "type": "string"
+            }
+          },
+          "required": [
+            "first_year",
+            "last_year",
+            "source",
+            "age"
+          ],
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "detailed": {
+          "additionalProperties": false,
+          "description": "pop_uf.parquet — idade simples por UF e sexo (projeções IBGE, 2000+)",
+          "properties": {
+            "age": {
+              "description": "Grão etário do arquivo",
+              "type": "string"
+            },
+            "age_groups": {
+              "description": "Faixas etárias quinquenais (só no arquivo agregado)",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "first_year": {
+              "description": "Primeiro ano coberto",
+              "type": "number"
+            },
+            "last_year": {
+              "description": "Último ano coberto",
+              "type": "number"
+            },
+            "source": {
+              "description": "Arquivo parquet que serve o intervalo",
+              "type": "string"
+            }
+          },
+          "required": [
+            "first_year",
+            "last_year",
+            "source",
+            "age"
+          ],
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "first_year": {
+          "description": "Primeiro ano com população por UF (união dos dois arquivos)",
+          "type": "number"
+        },
+        "last_year": {
+          "description": "Último ano com população por UF",
+          "type": "number"
+        }
+      },
+      "required": [
+        "first_year",
+        "last_year",
+        "detailed",
+        "aggregated"
+      ],
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "provenance": {
+      "additionalProperties": false,
+      "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença",
+      "properties": {
+        "citation": {
+          "description": "Citação pronta para uso",
+          "type": "string"
+        },
+        "data_vintage": {
+          "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "license": {
+          "description": "Regime legal do dado (id SPDX quando há)",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "retrieved_at": {
+          "description": "Instante REAL da extração na origem (ISO-8601)",
+          "type": "string"
+        },
+        "source": {
+          "description": "Fonte oficial do dado",
+          "type": "string"
+        },
+        "source_url": {
+          "description": "URL canônica que reproduz a consulta ou localiza a fonte",
+          "type": "string"
+        }
+      },
+      "required": [
+        "source",
+        "source_url",
+        "data_vintage",
+        "retrieved_at",
+        "citation",
+        "license"
+      ],
+      "type": "object"
+    },
+    "race_available": {
+      "additionalProperties": {
+        "description": "true quando o cubo tem raça/cor",
+        "type": "boolean"
+      },
+      "description": "Raça/cor disponível — chave é o ano (string)",
+      "type": "object"
+    },
+    "records_date_imputed": {
+      "additionalProperties": {
+        "description": "Internações que entraram com data imputada",
+        "type": "number"
+      },
+      "description": "Datas imputadas — chave é o ano (string)",
+      "type": "object"
+    },
+    "uf_basis": {
+      "additionalProperties": {
+        "description": "Base do eixo `uf`",
+        "enum": [
+          "residencia",
+          "arquivo"
+        ]
+      },
+      "description": "Base do eixo `uf` — chave é o ano (string)",
+      "type": "object"
+    },
+    "years": {
+      "description": "Anos com cubos Parquet presentes localmente",
+      "items": {
+        "type": "number"
+      },
+      "type": "array"
+    },
+    "years_cid9": {
+      "description": "Anos em que o cubo usa CID-9 (1992–1997)",
+      "items": {
+        "type": "number"
+      },
+      "type": "array"
+    },
+    "years_uf_arquivo": {
+      "description": "Anos em que `uf` é a do estabelecimento (1992–1997)",
+      "items": {
+        "type": "number"
+      },
+      "type": "array"
+    },
+    "years_without_race": {
+      "description": "Anos sem raça/cor (1998–2007)",
+      "items": {
+        "type": "number"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "provenance",
+    "attribution"
+  ],
+  "type": "object"
+}

Added value: +false