@lexnode/legal-data-sdk 1.24.0 → 1.26.0

package/README.md

@@ -51,7 +51,7 @@ Toda chamada manda `Authorization: Bearer`, `X-Request-Id`, `X-Trace-Id` e,
 quando há um, `X-Office-Id`; respeita o prazo do cliente **combinado** com o
 `signal` de quem chamou; e devolve `{ data, meta }` tipados pela rota. O `meta`
 é o do contrato mais `status` (o código HTTP) e `rateLimit` (os cabeçalhos
-`RateLimit-*` / `Retry-After`, lidos **inclusive no sucesso**).
+`RateLimit-*`, lidos **inclusive no sucesso**, e o `Retry-After` da recusa).
 
 Em `rateLimit`, use `remaining` para desacelerar: `resetSeconds` repete o que o
 cabeçalho `RateLimit-Reset` trouxe, e o motor lhe dá dois sentidos — segundos
@@ -259,10 +259,10 @@ if (desfecho.kind === "sync") {
 ## Ler um processo quando a fonte está lenta
 
 A ficha (`processes.get`) vai à fonte processual quando o acervo não tem o
-processo fresco; o retrato (`processes.snapshot`) vai sempre, e só recorre ao
-acervo quando a fonte falha. A fonte às vezes leva perto de um minuto por
-consulta. `waitSeconds` diz quanto o motor espera por ela: de 10 a 180
-segundos, padrão 20 na API.
+processo fresco; o retrato (`processes.snapshot`) vai sempre. Os dois só
+recorrem ao acervo quando a fonte falha (seção seguinte). A fonte às vezes leva
+perto de um minuto por consulta. `waitSeconds` diz quanto o motor espera por
+ela: de 10 a 180 segundos, padrão 20 na API.
 
 ```ts
 const { data, meta } = await lexnode.processes.get(numero, {
@@ -302,10 +302,91 @@ if (meta.partialIndex) {
 }
 ```
 
+Antes de recusar a resposta parcial que veio sem o processo porque partes do
+índice ficaram fora, o motor consulta a fonte de novo — até duas vezes, com uma
+pausa curta, enquanto a espera couber.
+
+**`meta.otherInstances`: o número tem outro documento na fonte.** A fonte pode
+guardar mais de um documento por número — em geral um por instância (1º grau,
+2º grau, turma recursal…), às vezes dois no mesmo grau —, e o motor serve e
+guarda um só: o de `data`, cujo grau está em `degree`. Quando a resposta da
+fonte trouxe outros, `meta.otherInstances` lista cada um com o grau (`grau`), a
+data em que a fonte o atualizou (`updatedAt`) e o órgão julgador (`courtBody`,
+quando vem). A lista não sai para processo restrito e não inclui documento que o
+motor classificaria como segredo de justiça.
+
+```ts
+for (const outra of meta.otherInstances ?? []) {
+  // Ex.: { grau: "G1", updatedAt: "2026-04-15T12:00:00.000Z" }
+}
+```
+
 **Agentes têm a espera deles.** No canal para agentes (MCP), as tools
 `ler_processo` e `consultar_processo` escolhem a espera em `maxWaitSeconds`, na
 mesma faixa e com padrão de 120 s; esse canal não passa pelo SDK.
 
+## Quando a fonte falha: o retrato guardado
+
+Quando a fonte processual falha — não responde dentro de `waitSeconds`, fica
+indisponível, responde com parte do índice sem poder servir o processo ou pede
+para esperar por volume — e o acervo guarda uma cópia do processo, a ficha
+(`processes.get`) e o retrato (`processes.snapshot`) respondem com essa cópia em
+vez do erro. A resposta diz que é cópia, e de quando:
+
+- `meta.lakeRescue.cause` diz por que a fonte não entregou: `UPSTREAM_TIMEOUT`,
+  `UPSTREAM_UNAVAILABLE` ou `UPSTREAM_RATE_LIMITED`;
+- `meta.lakeRescue.retryAfterSeconds`, repetido no header `Retry-After`, diz na
+  recusa por volume quanto esperar antes de consultar a fonte de novo. É a
+  espera da fonte, não do teto do motor: `meta.rateLimit.retryAfterSeconds`
+  fica `null` no sucesso;
+- `meta.sourceFetchedAt` diz quando a cópia foi buscada na fonte. Esse campo
+  acompanha toda resposta das duas leituras, socorrida ou não, menos a ficha
+  que o controle de confidencialidade entrega retida, sem o teor.
+
+A cópia custa 1 crédito, na ficha e no retrato. O retrato confere o saldo pelo
+preço cheio, 8, antes de ir à fonte; a ficha confere pelo preço do que
+entregou, depois da leitura. No retrato guardado, os movimentos são os da
+última vez que o motor buscou o processo, e `sourcePayload` é nulo: o que andou
+depois dessa data não está na resposta. Na ficha guardada, a data vale para os
+dados do processo, e o resumo das publicações (`djen`) é relido na hora.
+
+**Até que idade.** Sem pedir nada, só a cópia de até 24 h socorre a leitura —
+nessas duas rotas, uma resposta de sucesso já podia ser cópia do acervo dentro
+desse prazo. A cópia de qualquer idade vem com `staleOnFailure: true`:
+
+```ts
+import { describeFreshness, lakeRescueOf } from "@lexnode/legal-data-sdk";
+
+const retrato = await lexnode.processes.snapshot(numero, {
+  tribunalAlias: "api_publica_tjsp",
+  staleOnFailure: true,
+});
+
+const socorro = lakeRescueOf(retrato);
+if (socorro) {
+  // A fonte falhou e isto é a cópia guardada: o que andou depois de
+  // socorro.sourceFetchedAt não está aqui.
+  mostrar(describeFreshness(retrato));
+  // "cópia guardada em 26/09/2026, servida porque a fonte não respondeu a tempo"
+}
+```
+
+`lakeRescueOf` devolve `{ cause, sourceFetchedAt, retryAfterSeconds }` ou
+`null` — `sourceFetchedAt` é nulo na ficha retida —, e `sourceFetchedAtOf`
+devolve a data de qualquer resposta dessas leituras. As duas aceitam o envelope
+inteiro e o item do lote.
+
+**O que não é socorrido.** A resposta da fonte que não traz o processo segue
+404 `PROCESS_NOT_FOUND`, com cópia guardada ou sem ela: é a fonte dizendo que
+não tem o número, e não uma falha dela. A cópia passa pelo mesmo controle de
+confidencialidade da leitura; além de 24 h, só a recebe quem já tem interesse
+registrado no processo — de uma leitura anterior dele ou de uma assinatura
+ativa —, e os demais recebem a falha da fonte, como se não houvesse cópia.
+
+**No lote.** `processes.snapshotBatch` socorre só com a cópia de até 24 h. O
+item socorrido traz `lakeRescue` com a causa e a data, e custa 1 crédito em vez
+de 8.
+
 ## Frescor: o `total: 0` qualificado
 
 Um resultado vazio não distingue sozinho "não existe" de "a fonte ainda não

package/dist/client.js

@@ -66,12 +66,16 @@ function readHeaderNumber(headers, name) {
 /**
  * O teto por minuto sai em TODA resposta autenticada, não só na recusa. Lê-lo
  * no sucesso é o que permite ao consumidor desacelerar ANTES de bater no 429.
+ * O `Retry-After` só conta na recusa: no sucesso ele é a espera que a fonte
+ * pediu a uma leitura socorrida pelo acervo, e sai em `meta.lakeRescue`.
  */
-function readRateLimit(headers) {
+function readRateLimit(headers, succeeded) {
     const limit = readHeaderNumber(headers, "RateLimit-Limit");
     const remaining = readHeaderNumber(headers, "RateLimit-Remaining");
     const resetSeconds = readHeaderNumber(headers, "RateLimit-Reset");
-    const retryAfterSeconds = readHeaderNumber(headers, "Retry-After");
+    const retryAfterSeconds = succeeded
+        ? null
+        : readHeaderNumber(headers, "Retry-After");
     if (limit === null &&
         remaining === null &&
         resetSeconds === null &&
@@ -272,7 +276,7 @@ export function createLexNodeClient(options) {
                 // corpo de outro host como se fosse a resposta do motor.
                 redirect: "error",
             });
-            rateLimit = readRateLimit(response.headers);
+            rateLimit = readRateLimit(response.headers, response.ok);
             // A leitura do corpo fica DENTRO do prazo: um corpo que trava depois dos
             // cabeçalhos pendura a chamada por tempo indefinido se o vínculo já tiver
             // sido desfeito aqui.

package/dist/freshness.d.ts

@@ -7,6 +7,10 @@
  * publica a data-limite do índice em dois eixos — `updatedThrough` na busca de
  * processo, `lastEditionDate` na leitura do diário — e este módulo é a leitura
  * dos dois pelo mesmo nome.
+ *
+ * A leitura de UM processo diz também de quando são os dados servidos
+ * (`meta.sourceFetchedAt`) e, quando a fonte falhou e o acervo socorreu, que a
+ * resposta é a cópia guardada (`meta.lakeRescue`).
  */
 export type FreshnessAxis = "PROCESS" | "PUBLICATION";
 export type FreshnessState = 
@@ -44,5 +48,40 @@ export interface NotYetIndexedOptions {
  * data-limite que cobre o que se perguntou: aí o vazio é resposta.
  */
 export declare function isNotYetIndexed(result: unknown, options?: NotYetIndexedOptions): boolean;
-/** Uma frase em pt-BR sobre o alcance da fonte, pronta para a tela. */
+/** Por que a fonte não entregou o processo que o acervo socorreu. */
+export type LakeRescueCause = "UPSTREAM_TIMEOUT" | "UPSTREAM_UNAVAILABLE" | "UPSTREAM_RATE_LIMITED";
+/**
+ * A leitura de UM processo cuja fonte falhou e que o motor serviu com a cópia
+ * que o acervo guarda.
+ */
+export interface LakeRescue {
+    /**
+     * A causa, pelo código público da taxonomia. Valor novo pode entrar no
+     * contrato; trate o desconhecido como "a fonte falhou".
+     */
+    cause: LakeRescueCause | (string & {});
+    /**
+     * Quando a cópia servida foi buscada na fonte; nulo na ficha que o controle
+     * de confidencialidade entrega retida, que sai sem a data.
+     */
+    sourceFetchedAt: Date | null;
+    /** A espera que a fonte pediu, na recusa por volume. */
+    retryAfterSeconds: number | null;
+}
+/**
+ * O socorro pelo acervo, ou `null` quando a resposta veio da fonte ou do
+ * acervo em dia. Aceita o envelope inteiro (`{ data, meta }`) ou o item do
+ * lote de retratos; só o `data` não traz a marca.
+ */
+export declare function lakeRescueOf(result: unknown): LakeRescue | null;
+/**
+ * Quando os dados servidos foram buscados na fonte: `meta.sourceFetchedAt` das
+ * leituras de um processo, ou a data do item socorrido do lote.
+ */
+export declare function sourceFetchedAtOf(result: unknown): Date | null;
+/**
+ * Uma frase em pt-BR sobre o frescor da resposta, pronta para a tela: a cópia
+ * guardada e o porquê, quando o acervo socorreu a fonte; senão, até onde a
+ * fonte foi lida.
+ */
 export declare function describeFreshness(result: unknown): string;

package/dist/freshness.js

@@ -7,6 +7,10 @@
  * publica a data-limite do índice em dois eixos — `updatedThrough` na busca de
  * processo, `lastEditionDate` na leitura do diário — e este módulo é a leitura
  * dos dois pelo mesmo nome.
+ *
+ * A leitura de UM processo diz também de quando são os dados servidos
+ * (`meta.sourceFetchedAt`) e, quando a fonte falhou e o acervo socorreu, que a
+ * resposta é a cópia guardada (`meta.lakeRescue`).
  */
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -96,8 +100,88 @@ function ddmmaaaa(date) {
     const mes = String(date.getUTCMonth() + 1).padStart(2, "0");
     return `${dia}/${mes}/${date.getUTCFullYear()}`;
 }
-/** Uma frase em pt-BR sobre o alcance da fonte, pronta para a tela. */
+function toInstant(value) {
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value;
+    }
+    return toDate(value);
+}
+/**
+ * A marca do socorro e a data da cópia, onde quer que elas venham: no `meta`
+ * do envelope das leituras de um processo, ou no item do lote de retratos,
+ * que leva as duas em `lakeRescue`.
+ */
+function rescueFieldsOf(result) {
+    const record = asRecord(result);
+    const meta = asRecord(record?.meta);
+    if (meta) {
+        return {
+            rescue: asRecord(meta.lakeRescue),
+            fetchedAt: meta.sourceFetchedAt,
+        };
+    }
+    const itemRescue = asRecord(record?.lakeRescue);
+    return { rescue: itemRescue, fetchedAt: itemRescue?.sourceFetchedAt };
+}
+/**
+ * O socorro pelo acervo, ou `null` quando a resposta veio da fonte ou do
+ * acervo em dia. Aceita o envelope inteiro (`{ data, meta }`) ou o item do
+ * lote de retratos; só o `data` não traz a marca.
+ */
+export function lakeRescueOf(result) {
+    const { rescue, fetchedAt } = rescueFieldsOf(result);
+    if (!rescue || typeof rescue.cause !== "string")
+        return null;
+    return {
+        cause: rescue.cause,
+        sourceFetchedAt: toInstant(fetchedAt),
+        retryAfterSeconds: typeof rescue.retryAfterSeconds === "number"
+            ? rescue.retryAfterSeconds
+            : null,
+    };
+}
+/**
+ * Quando os dados servidos foram buscados na fonte: `meta.sourceFetchedAt` das
+ * leituras de um processo, ou a data do item socorrido do lote.
+ */
+export function sourceFetchedAtOf(result) {
+    return toInstant(rescueFieldsOf(result).fetchedAt);
+}
+const BRASILIA_DATE = new Intl.DateTimeFormat("pt-BR", {
+    day: "2-digit",
+    month: "2-digit",
+    year: "numeric",
+    timeZone: "America/Sao_Paulo",
+});
+/** O dia de um instante no horário de Brasília, montado pelas partes. */
+function ddmmaaaaBrasilia(date) {
+    const parts = Object.fromEntries(BRASILIA_DATE.formatToParts(date).map((part) => [part.type, part.value]));
+    return `${parts.day}/${parts.month}/${parts.year}`;
+}
+const RESCUE_REASON = {
+    UPSTREAM_TIMEOUT: "não respondeu a tempo",
+    UPSTREAM_UNAVAILABLE: "não conseguiu entregar o processo",
+    UPSTREAM_RATE_LIMITED: "pediu para esperar por volume",
+};
+function rescueReason(cause) {
+    return cause in RESCUE_REASON
+        ? RESCUE_REASON[cause]
+        : "falhou";
+}
+/**
+ * Uma frase em pt-BR sobre o frescor da resposta, pronta para a tela: a cópia
+ * guardada e o porquê, quando o acervo socorreu a fonte; senão, até onde a
+ * fonte foi lida.
+ */
 export function describeFreshness(result) {
+    const rescue = lakeRescueOf(result);
+    if (rescue) {
+        const date = rescue.sourceFetchedAt
+            ? ` em ${ddmmaaaaBrasilia(rescue.sourceFetchedAt)}`
+            : "";
+        const reason = rescueReason(rescue.cause);
+        return `cópia guardada${date}, servida porque a fonte ${reason}`;
+    }
     const { readThrough: limite } = freshnessOf(result);
     return limite
         ? `fonte lida até ${ddmmaaaa(limite)}`

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { paginate } from "./paginate.js";
 export type { PaginateOptions } from "./paginate.js";
 export { searchProcesses, waitForSearchJob } from "./search.js";
 export type { ProcessSearchOutcome, ProcessSearchResult, QueuedSearchJob, SearchJob, SearchJobState, WaitForSearchJobOptions, } from "./search.js";
-export { describeFreshness, freshnessOf, isNotYetIndexed, readThrough, } from "./freshness.js";
-export type { Freshness, FreshnessAxis, FreshnessState, NotYetIndexedOptions, } from "./freshness.js";
+export { describeFreshness, freshnessOf, isNotYetIndexed, lakeRescueOf, readThrough, sourceFetchedAtOf, } from "./freshness.js";
+export type { Freshness, FreshnessAxis, FreshnessState, LakeRescue, LakeRescueCause, NotYetIndexedOptions, } from "./freshness.js";
 export { isFirstAppearance, resubscribeOnFirstAppearance, unwatchProcess, watchProcess, } from "./watch.js";
 export type { FirstAppearanceEvent, ResubscribeSubscriber, UnwatchProcessInput, WatchProcessInput, WatchProcessResult, } from "./watch.js";

package/dist/index.js

@@ -13,5 +13,5 @@ export { LEXNODE_ERROR_CODES, LexNodeError, isLexNodeError } from "./errors.js";
 export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, LEXNODE_WEBHOOK_HEADERS, WEBHOOK_EVENT_TYPES, WEBHOOK_TEST_EVENT_TYPE, isKnownWebhookEventType, isReceiverFault, isWebhookTest, parseWebhookEvent, verifyWebhookSignature, webhookRejectionStatus, } from "./webhooks.js";
 export { paginate } from "./paginate.js";
 export { searchProcesses, waitForSearchJob } from "./search.js";
-export { describeFreshness, freshnessOf, isNotYetIndexed, readThrough, } from "./freshness.js";
+export { describeFreshness, freshnessOf, isNotYetIndexed, lakeRescueOf, readThrough, sourceFetchedAtOf, } from "./freshness.js";
 export { isFirstAppearance, resubscribeOnFirstAppearance, unwatchProcess, watchProcess, } from "./watch.js";

package/dist/types.d.ts

@@ -89,7 +89,11 @@ export interface RateLimitSnapshot {
      * dormir a janela inteira — para desacelerar, olhe `remaining`.
      */
     resetSeconds: number | null;
-    /** O `Retry-After` da recusa, quando houve. */
+    /**
+     * O `Retry-After` da recusa, quando houve; `null` em todo sucesso. A espera
+     * que a fonte pediu a uma leitura socorrida pelo acervo sai em
+     * `meta.lakeRescue.retryAfterSeconds`.
+     */
     retryAfterSeconds: number | null;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexnode/legal-data-sdk",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "description": "Cliente TypeScript do LexNode, o motor de dados jur\u00eddicos do Brasil: transporte tipado, erros classificados, verifica\u00e7\u00e3o de webhook e os tipos gerados do contrato OpenAPI.",
   "license": "MIT",
   "homepage": "https://www.lexnode.com.br/docs",

package/schema.d.ts

@@ -159,7 +159,7 @@ export interface paths {
         };
         /**
          * Obter um processo pelo número
-         * @description Retorna o registro exato do processo para o tribunal e o número informados, com resolução cache-first quando disponível. `waitSeconds` escolhe quanto esperar pela fonte processual. Quando a fonte responde com parte do índice e o processo está na parte que respondeu, ele é servido e `meta.partialIndex` diz quantas partes falharam (`shardsFailed`), de quantas (`shardsTotal`) e se o prazo interno da fonte estourou (`timedOut`): outra instância do mesmo número, se existir, pode não ter vindo. A exceção é o processo que veio de uma instância diferente da que o acervo já guarda do número: a guardada pode estar na parte que não respondeu, e a resposta parcial não é servida. Resposta parcial que não serve o processo — sem ele, ou com a outra instância — é 502 `UPSTREAM_UNAVAILABLE` retentável, nunca 404.
+         * @description Retorna o registro exato do processo para o tribunal e o número informados, com resolução cache-first quando disponível. `meta.sourceFetchedAt` diz quando os dados servidos foram buscados na fonte; a ficha retida pelo controle de confidencialidade, sem o teor, não o traz. `waitSeconds` escolhe quanto esperar pela fonte processual. Quando a fonte responde com parte do índice e o processo está na parte que respondeu, ele é servido e `meta.partialIndex` diz quantas partes falharam (`shardsFailed`), de quantas (`shardsTotal`) e se o prazo interno da fonte estourou (`timedOut`): outra instância do mesmo número, se existir, pode não ter vindo. A exceção é o processo que veio de uma instância diferente da que o acervo já guarda do número: a guardada pode estar na parte que não respondeu, e a resposta parcial não é servida. Resposta parcial que não serve o processo — sem ele, ou com a outra instância — é 502 `UPSTREAM_UNAVAILABLE` retentável, nunca 404; antes dela, o motor consulta a fonte de novo, até duas vezes, enquanto o prazo de `waitSeconds` couber. Quando a resposta traz mais de um documento do número — em geral um por instância, mas dois podem ser do mesmo grau —, o motor serve e guarda um só, o de `data` (grau em `degree`), e `meta.otherInstances` lista os outros que vieram: grau, data de atualização na fonte e órgão julgador. **Quando a fonte falha** — não responde dentro de `waitSeconds`, fica indisponível, responde com parte do índice sem poder servir o processo ou pede para esperar por volume — e o acervo guarda uma cópia do processo, a resposta é essa cópia, por 1 crédito: `meta.lakeRescue.cause` diz a causa e `meta.sourceFetchedAt` a data em que a cópia foi buscada. Movimentos posteriores a essa data podem existir e não estão na resposta. Sem `staleOnFailure=true`, só a cópia de até 24 h socorre; com ele, a de qualquer idade. Na recusa por volume, `meta.lakeRescue.retryAfterSeconds` e o header `Retry-After` dizem quanto esperar antes de consultar de novo. A resposta da fonte que não traz o processo nunca é socorrida e segue 404. A cópia passa pelo mesmo controle de confidencialidade da leitura; além de 24 h, só a recebe quem já tem interesse registrado no processo — de uma leitura anterior dele ou de uma assinatura ativa —, e os demais recebem a falha da fonte. Na ficha socorrida pelo acervo, a data vale para os dados do processo, e o resumo das publicações (`djen`) é relido na hora das publicações que o acervo guarda.
          *
          *     **Escopo exigido na chave de API:** `PROCESSES_READ`
          */
@@ -203,7 +203,7 @@ export interface paths {
         };
         /**
          * Obter um snapshot vivo do processo
-         * @description Busca o hit exato do processo no upstream do CNJ e retorna o registro normalizado do processo, o payload bruto da fonte e as movimentações CNJ normalizadas. `waitSeconds` escolhe quanto esperar pela fonte processual. Quando a fonte responde com parte do índice e o processo está na parte que respondeu, ele é servido e `meta.partialIndex` diz quantas partes falharam (`shardsFailed`), de quantas (`shardsTotal`) e se o prazo interno da fonte estourou (`timedOut`): outra instância do mesmo número, se existir, pode não ter vindo. A exceção é o processo que veio de uma instância diferente da que o acervo já guarda do número: a guardada pode estar na parte que não respondeu, e a resposta parcial não é servida. Resposta parcial que não serve o processo — sem ele, ou com a outra instância — é 502 `UPSTREAM_UNAVAILABLE` retentável, nunca 404.
+         * @description Busca o processo na fonte processual e retorna o registro normalizado do processo, o payload bruto da fonte e as movimentações normalizadas. `meta.sourceFetchedAt` diz quando os dados servidos foram buscados na fonte; a ficha retida pelo controle de confidencialidade, sem o teor, não o traz. `waitSeconds` escolhe quanto esperar pela fonte processual. Quando a fonte responde com parte do índice e o processo está na parte que respondeu, ele é servido e `meta.partialIndex` diz quantas partes falharam (`shardsFailed`), de quantas (`shardsTotal`) e se o prazo interno da fonte estourou (`timedOut`): outra instância do mesmo número, se existir, pode não ter vindo. A exceção é o processo que veio de uma instância diferente da que o acervo já guarda do número: a guardada pode estar na parte que não respondeu, e a resposta parcial não é servida. Resposta parcial que não serve o processo — sem ele, ou com a outra instância — é 502 `UPSTREAM_UNAVAILABLE` retentável, nunca 404; antes dela, o motor consulta a fonte de novo, até duas vezes, enquanto o prazo de `waitSeconds` couber. Quando a resposta traz mais de um documento do número — em geral um por instância, mas dois podem ser do mesmo grau —, o motor serve e guarda um só, o de `data` (grau em `degree`), e `meta.otherInstances` lista os outros que vieram: grau, data de atualização na fonte e órgão julgador. **Quando a fonte falha** — não responde dentro de `waitSeconds`, fica indisponível, responde com parte do índice sem poder servir o processo ou pede para esperar por volume — e o acervo guarda uma cópia do processo, a resposta é essa cópia, por 1 crédito: `meta.lakeRescue.cause` diz a causa e `meta.sourceFetchedAt` a data em que a cópia foi buscada. Movimentos posteriores a essa data podem existir e não estão na resposta. Sem `staleOnFailure=true`, só a cópia de até 24 h socorre; com ele, a de qualquer idade. Na recusa por volume, `meta.lakeRescue.retryAfterSeconds` e o header `Retry-After` dizem quanto esperar antes de consultar de novo. A resposta da fonte que não traz o processo nunca é socorrida e segue 404. A cópia passa pelo mesmo controle de confidencialidade da leitura; além de 24 h, só a recebe quem já tem interesse registrado no processo — de uma leitura anterior dele ou de uma assinatura ativa —, e os demais recebem a falha da fonte. No retrato socorrido pelo acervo, os movimentos e o registro do processo são os da última captura guardada, e `sourcePayload` é nulo: o documento bruto da fonte não é guardado.
          *
          *     **Escopo exigido na chave de API:** `PROCESSES_READ`
          */
@@ -249,7 +249,7 @@ export interface paths {
         put?: never;
         /**
          * Snapshot em lote
-         * @description Snapshot de até N processos em uma única ida e volta (elimina o N+1 noturno de uma chamada por processo). Sucesso parcial: item que falha é reportado individualmente e nunca derruba o lote; só os itens bem-sucedidos são cobrados. Todo snapshot obtido é gravado de volta no data lake.
+         * @description Snapshot de até N processos em uma única ida e volta (elimina o N+1 noturno de uma chamada por processo). Sucesso parcial: item que falha é reportado individualmente e nunca derruba o lote; só os itens bem-sucedidos são cobrados. Todo snapshot obtido é gravado de volta no data lake. Quando a fonte processual falha num item e o acervo guarda uma cópia dele de até 24 h, o item sai com essa cópia e com `lakeRescue` (a causa e a data da cópia), e custa 1 crédito em vez de 8; cópia mais velha não socorre o lote.
          *
          *     **Escopo exigido na chave de API:** `PROCESSES_READ`
          */
@@ -2043,6 +2043,8 @@ export interface operations {
                 since?: unknown;
                 /** @description Quanto esperar pela fonte processual quando o processo precisa ser buscado nela, em segundos: de 10 a 180, padrão 20. É o teto da consulta à fonte: ela às vezes leva até ~60 s por consulta, cada ida a ela espera no máximo 60 s, e a segunda ida só sai depois de uma recusa por volume ou de um erro da fonte, nunca depois de tempo esgotado. Depois dela, a ficha ainda espera até 10 s pelo resumo das publicações do processo. Tempo esgotado é 504 `UPSTREAM_TIMEOUT` (lentidão, não ausência). Dê ao seu cliente HTTP um tempo limite que cubra a espera, esses segundos da ficha e a rede: no padrão, mais de 30 s. */
                 waitSeconds?: number;
+                /** @description O que fazer quando a fonte processual falha — não responde dentro da espera, fica indisponível ou pede para esperar por volume — e o acervo guarda uma cópia do processo. Sem ele (`false`), a cópia só é servida se tiver até 24 h. Com `true`, ela é servida de qualquer idade. Nos dois casos a resposta custa 1 crédito, `meta.lakeRescue` diz a causa e `meta.sourceFetchedAt` diz quando a cópia foi buscada na fonte. A resposta da fonte que não traz o processo segue 404 `PROCESS_NOT_FOUND`, com cópia guardada ou sem ela. */
+                staleOnFailure?: boolean;
             };
             header?: {
                 /** @description Identificador da requisição escolhido pelo cliente, ecoado em meta.requestId e no corpo de erro. Tem DOIS papéis: (1) rastreio, em toda rota — é por ele que o suporte encontra a chamada; (2) idempotência por conta em POST /v1/publications/text-searches e POST /v1/search-jobs, onde reenviar o mesmo valor reapresenta o resultado já produzido, sem nova cobrança. Fora dessas duas rotas o valor não deduplica nada: para repetir uma chamada de propósito, mande um valor novo. Aceita [A-Za-z0-9_.:-], até 200 caracteres; valor fora disso é ignorado e o motor cunha o próprio. */
@@ -2122,6 +2124,21 @@ export interface operations {
                             requestId: string;
                             credits?: number;
                             cacheHit?: boolean;
+                            /**
+                             * Format: date-time
+                             * @description Quando os dados servidos foram buscados na fonte: agora, se ela respondeu; antes, se vieram do acervo. No retrato socorrido pelo acervo, é a data da captura dos movimentos servidos. Ausente na ficha que o controle de confidencialidade entrega retida, sem o teor.
+                             */
+                            sourceFetchedAt?: string;
+                            /** @description Presente só quando a fonte processual falhou e o motor serviu a cópia que o acervo guarda do processo. A data da cópia está em `meta.sourceFetchedAt`; movimentos posteriores a ela podem existir e não estão na resposta. */
+                            lakeRescue?: {
+                                /**
+                                 * @description Por que a fonte não entregou: `UPSTREAM_TIMEOUT` (não respondeu dentro da espera), `UPSTREAM_UNAVAILABLE` (indisponível, ou respondeu com parte do índice sem poder servir o processo) ou `UPSTREAM_RATE_LIMITED` (pediu para esperar por volume).
+                                 * @enum {string}
+                                 */
+                                cause: "UPSTREAM_TIMEOUT" | "UPSTREAM_UNAVAILABLE" | "UPSTREAM_RATE_LIMITED";
+                                /** @description A espera que a fonte pediu: não consulte a fonte de novo antes dela. */
+                                retryAfterSeconds?: number;
+                            };
                             /** @description Presente só quando a fonte respondeu com parte do índice e o processo estava na parte que respondeu: outra instância do mesmo número, se existir, pode não ter vindo. */
                             partialIndex?: {
                                 /** @description Partes do índice da fonte que não responderam. */
@@ -2131,6 +2148,18 @@ export interface operations {
                                 /** @description A fonte estourou o próprio prazo interno e devolveu só o que deu tempo de olhar. */
                                 timedOut: boolean;
                             };
+                            /** @description Presente só quando a resposta da fonte trouxe mais de um documento do número — em geral de instâncias diferentes, mas dois podem ter o mesmo `grau`. O motor serve e guarda um só (o de `data`, que diz o grau em `degree`); estes são os outros que vieram na mesma resposta. Não inclui documento que o motor classificaria como segredo de justiça, e não aparece quando o processo servido é restrito. */
+                            otherInstances?: {
+                                /** @description O grau deste documento na fonte: G1, G2, JE, TR… */
+                                grau: string | null;
+                                /**
+                                 * Format: date-time
+                                 * @description Quando a fonte atualizou este documento pela última vez.
+                                 */
+                                updatedAt: string | null;
+                                /** @description O órgão julgador deste documento, quando a fonte o traz. */
+                                courtBody?: string;
+                            }[];
                         } & {
                             [key: string]: unknown;
                         };
@@ -2664,6 +2693,8 @@ export interface operations {
                 since?: unknown;
                 /** @description Quanto esperar pela fonte processual quando o processo precisa ser buscado nela, em segundos: de 10 a 180, padrão 20. É o teto da consulta à fonte: ela às vezes leva até ~60 s por consulta, cada ida a ela espera no máximo 60 s, e a segunda ida só sai depois de uma recusa por volume ou de um erro da fonte, nunca depois de tempo esgotado. Depois dela, a ficha ainda espera até 10 s pelo resumo das publicações do processo. Tempo esgotado é 504 `UPSTREAM_TIMEOUT` (lentidão, não ausência). Dê ao seu cliente HTTP um tempo limite que cubra a espera, esses segundos da ficha e a rede: no padrão, mais de 30 s. */
                 waitSeconds?: number;
+                /** @description O que fazer quando a fonte processual falha — não responde dentro da espera, fica indisponível ou pede para esperar por volume — e o acervo guarda uma cópia do processo. Sem ele (`false`), a cópia só é servida se tiver até 24 h. Com `true`, ela é servida de qualquer idade. Nos dois casos a resposta custa 1 crédito, `meta.lakeRescue` diz a causa e `meta.sourceFetchedAt` diz quando a cópia foi buscada na fonte. A resposta da fonte que não traz o processo segue 404 `PROCESS_NOT_FOUND`, com cópia guardada ou sem ela. */
+                staleOnFailure?: boolean;
             };
             header?: {
                 /** @description Identificador da requisição escolhido pelo cliente, ecoado em meta.requestId e no corpo de erro. Tem DOIS papéis: (1) rastreio, em toda rota — é por ele que o suporte encontra a chamada; (2) idempotência por conta em POST /v1/publications/text-searches e POST /v1/search-jobs, onde reenviar o mesmo valor reapresenta o resultado já produzido, sem nova cobrança. Fora dessas duas rotas o valor não deduplica nada: para repetir uma chamada de propósito, mande um valor novo. Aceita [A-Za-z0-9_.:-], até 200 caracteres; valor fora disso é ignorado e o motor cunha o próprio. */
@@ -2755,6 +2786,21 @@ export interface operations {
                             requestId: string;
                             credits?: number;
                             cacheHit?: boolean;
+                            /**
+                             * Format: date-time
+                             * @description Quando os dados servidos foram buscados na fonte: agora, se ela respondeu; antes, se vieram do acervo. No retrato socorrido pelo acervo, é a data da captura dos movimentos servidos. Ausente na ficha que o controle de confidencialidade entrega retida, sem o teor.
+                             */
+                            sourceFetchedAt?: string;
+                            /** @description Presente só quando a fonte processual falhou e o motor serviu a cópia que o acervo guarda do processo. A data da cópia está em `meta.sourceFetchedAt`; movimentos posteriores a ela podem existir e não estão na resposta. */
+                            lakeRescue?: {
+                                /**
+                                 * @description Por que a fonte não entregou: `UPSTREAM_TIMEOUT` (não respondeu dentro da espera), `UPSTREAM_UNAVAILABLE` (indisponível, ou respondeu com parte do índice sem poder servir o processo) ou `UPSTREAM_RATE_LIMITED` (pediu para esperar por volume).
+                                 * @enum {string}
+                                 */
+                                cause: "UPSTREAM_TIMEOUT" | "UPSTREAM_UNAVAILABLE" | "UPSTREAM_RATE_LIMITED";
+                                /** @description A espera que a fonte pediu: não consulte a fonte de novo antes dela. */
+                                retryAfterSeconds?: number;
+                            };
                             /** @description Presente só quando a fonte respondeu com parte do índice e o processo estava na parte que respondeu: outra instância do mesmo número, se existir, pode não ter vindo. */
                             partialIndex?: {
                                 /** @description Partes do índice da fonte que não responderam. */
@@ -2764,6 +2810,18 @@ export interface operations {
                                 /** @description A fonte estourou o próprio prazo interno e devolveu só o que deu tempo de olhar. */
                                 timedOut: boolean;
                             };
+                            /** @description Presente só quando a resposta da fonte trouxe mais de um documento do número — em geral de instâncias diferentes, mas dois podem ter o mesmo `grau`. O motor serve e guarda um só (o de `data`, que diz o grau em `degree`); estes são os outros que vieram na mesma resposta. Não inclui documento que o motor classificaria como segredo de justiça, e não aparece quando o processo servido é restrito. */
+                            otherInstances?: {
+                                /** @description O grau deste documento na fonte: G1, G2, JE, TR… */
+                                grau: string | null;
+                                /**
+                                 * Format: date-time
+                                 * @description Quando a fonte atualizou este documento pela última vez.
+                                 */
+                                updatedAt: string | null;
+                                /** @description O órgão julgador deste documento, quando a fonte o traz. */
+                                courtBody?: string;
+                            }[];
                         } & {
                             [key: string]: unknown;
                         };
@@ -3338,6 +3396,21 @@ export interface operations {
                                     };
                                     movements: unknown[];
                                 };
+                                /** @description Presente só no item que a fonte processual não entregou e que o acervo socorreu com a cópia guardada de até 24 h: a causa, a espera que a fonte pediu, quando pediu, e quando a cópia foi buscada. O item socorrido custa 1 crédito. */
+                                lakeRescue?: {
+                                    /**
+                                     * @description Por que a fonte não entregou: `UPSTREAM_TIMEOUT` (não respondeu dentro da espera), `UPSTREAM_UNAVAILABLE` (indisponível, ou respondeu com parte do índice sem poder servir o processo) ou `UPSTREAM_RATE_LIMITED` (pediu para esperar por volume).
+                                     * @enum {string}
+                                     */
+                                    cause: "UPSTREAM_TIMEOUT" | "UPSTREAM_UNAVAILABLE" | "UPSTREAM_RATE_LIMITED";
+                                    /** @description A espera que a fonte pediu: não consulte a fonte de novo antes dela. */
+                                    retryAfterSeconds?: number;
+                                    /**
+                                     * Format: date-time
+                                     * @description Quando a cópia servida foi buscada na fonte.
+                                     */
+                                    sourceFetchedAt: string;
+                                };
                                 error?: {
                                     status?: number;
                                     /** @description Código estável da taxonomia, quando a falha do item o carrega — é o que distingue, por exemplo, a recusa da chave de teste de um bloqueio LGPD. */