@lexnode/legal-data-sdk 1.25.0 → 1.27.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
@@ -194,6 +194,14 @@ switch (resultado.event.type) {
     break;
   case "PROCESS_MOVEMENT_CREATED":
     resultado.event.payload.externalRef;
+    resultado.event.payload.degree; // o grau do movimento mais recente
+    break;
+  case "PROCESS_INSTANCE_DISCOVERED":
+    // Outro grau do processo apareceu na fonte; o histórico dele está no
+    // retrato, em `instances`. O processo retido vem sem o grau.
+    if (!resultado.event.payload.contentWithheld) {
+      resultado.event.payload.degree;
+    }
     break;
   case "SEARCH_JOB_COMPLETED":
     if (resultado.event.payload.status === "FAILED") {
@@ -256,13 +264,101 @@ if (desfecho.kind === "sync") {
 }
 ```
 
+## Um número, várias instâncias
+
+A fonte processual guarda um documento por instância do processo — 1º grau, 2º
+grau, turma recursal… —, às vezes dois do mesmo grau, e o motor guarda cada um
+na sua instância.
+
+**O topo não troca.** O topo da ficha (`data`) e do retrato (`data.process` e
+`data.movements`) é sempre a instância principal do número, com o grau em
+`degree`: a mesma de uma leitura para a outra, qualquer que seja a ordem em que
+a fonte devolve os documentos. Ela só muda quando uma resposta completa da
+fonte pelo número deixa de trazê-la. Quem compara movimentos pela chave não vê
+o histórico de outro grau aparecer como novo no topo — e o topo pode não ser o
+grau que anda: o 2º grau guardado primeiro continua no topo enquanto o 1º se
+move.
+
+**Todos os graus em `instances`.** A ficha e o retrato listam em `instances`
+todos os documentos que o motor guarda do número, a principal primeiro
+(`primary: true`). Cada um diz de onde veio nesta resposta (`origin`: `SOURCE`
+quando a fonte o trouxe, `LAKE` quando saiu do acervo), quando foi buscado
+(`fetchedAt`) e desde quando a resposta completa da fonte vem sem ele
+(`absentSince`). No retrato, cada instância traz os movimentos da última captura
+dela, do mais recente ao mais antigo e sem o payload bruto da fonte; a que o
+motor nunca capturou vem com `movementsCaptured: false` e `movements` nulo, nunca
+com lista vazia, que diria que o grau não andou. Todos os documentos levam a
+classificação do número inteiro — basta um em segredo de justiça para todos
+saírem marcados —, e a ficha retida pelo controle de confidencialidade sai sem a
+lista.
+
+```ts
+const { data } = await lexnode.processes.snapshot(numero, { tribunalAlias });
+
+for (const instancia of data.instances) {
+  instancia.degree; // "G1", "G2", "TR"…
+  instancia.primary; // true só na do topo
+  instancia.movements ?? "movimentos nunca capturados";
+}
+```
+
+No lote (`processes.snapshotBatch`), `instances` traz só o cabeçalho de cada
+documento; os movimentos de cada instância vêm no retrato de um processo. A
+busca por número completo servida do acervo devolve um item por documento que a
+fonte ainda traz do número, a principal primeiro; quando eles não cabem em
+`limit`, a busca vai à fonte, que pagina.
+
+**Recorte por grau.** A lista de movimentações aceita `degree` e devolve só os
+movimentos que o documento daquele grau trouxe na última captura; cada item diz
+em `degrees` o grau — ou os graus, quando o mesmo ato está nos dois documentos
+— que o trouxe, e vem vazio no movimento que nenhuma captura atual traz.
+
+```ts
+const { data } = await lexnode.processes.movements(numero, {
+  tribunalAlias,
+  degree: "G1",
+});
+data.items; // só o que o 1º grau trouxe
+```
+
+**O grau novo chega num evento só.** Quando outro grau de um processo assinado
+aparece na fonte, o histórico dele entra no acervo sem virar
+`PROCESS_MOVEMENT_CREATED` movimento a movimento: chega um
+`PROCESS_INSTANCE_DISCOVERED`, com o grau, o órgão julgador e as contagens —
+`historyMovementCount` entrou sem aviso próprio, `announcedMovementCount` saiu
+também como movimento novo. O `PROCESS_MOVEMENT_CREATED` diz o grau do
+movimento mais recente (`degree`, `instanceSourceId`) e quantos movimentos novos
+vieram de cada grau (`instances`). Assine os dois: quem assina só o movimento
+não fica sabendo do grau que apareceu.
+
+**`meta.otherInstances`: o resumo do que veio.** Quando a resposta da fonte traz
+outros documentos do número além da principal, `meta.otherInstances` resume 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; os
+documentos inteiros estão em `instances`.
+
+```ts
+for (const outra of meta.otherInstances ?? []) {
+  // Ex.: { grau: "G1", updatedAt: "2026-04-15T12:00:00.000Z" }
+}
+```
+
+**Continuação.** Na API nada é cortado: o retrato traz os movimentos guardados
+de cada instância, e a lista de movimentações lê do acervo, grau a grau, sem ir
+à fonte. No canal para agentes (MCP), `consultar_processo` cabe no teto de uma
+resposta: de cada grau vêm os movimentos mais recentes, o grau que se moveu por
+último primeiro, e a mesma tool com `grau` e `pagina` traz os seguintes do que o
+motor guardou, por 1 crédito e sem ir à fonte — só para quem já leu o processo
+ou o acompanha.
+
 ## 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, {
@@ -290,15 +386,15 @@ ou a vigília do processo (`watchProcess`), que consulta em segundo plano.
 responde com só parte do índice e o processo estava na parte que respondeu, ele
 é servido, e `meta.partialIndex` diz quantas partes falharam (`shardsFailed`),
 de quantas (`shardsTotal`, nulo quando a fonte não as contou) e se o prazo
-interno dela estourou (`timedOut`). O processo servido é o que a fonte tem, mas
-outra instância do mesmo número — outro grau — pode estar na parte que não
-respondeu. A resposta parcial que não serve o processo — sem ele, ou com uma
-instância diferente da que o acervo já guarda — é 502 `UPSTREAM_UNAVAILABLE`
+interno dela estourou (`timedOut`). O documento que o acervo já guardava e não
+veio sai em `instances` do acervo (`origin: "LAKE"`), com a data dele, e outro
+grau que o acervo não conhece, se existir, pode estar na parte que não
+respondeu. A resposta parcial sem o processo é 502 `UPSTREAM_UNAVAILABLE`
 retentável, nunca 404.
 
 ```ts
 if (meta.partialIndex) {
-  // Outro grau deste número, se existir, pode não ter vindo.
+  // Outro grau deste número que o acervo não conhece pode não ter vindo.
 }
 ```
 
@@ -306,24 +402,74 @@ 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.
+**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, cada instância traz os
+movimentos da última vez que o motor a buscou, com a data em
+`instances[].fetchedAt`, e `sourcePayload` é nulo: o que andou depois dessas
+datas não está na resposta. O número que a resposta completa mais recente da
+fonte já não trazia em documento nenhum não é socorrido. 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
-for (const outra of meta.otherInstances ?? []) {
-  // Ex.: { grau: "G1", updatedAt: "2026-04-15T12:00:00.000Z" }
+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"
 }
 ```
 
-**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.
+`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
 

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

@@ -15,12 +15,12 @@ export { LEXNODE_ERROR_CODES, LexNodeError, isLexNodeError } from "./errors.js";
 export type { LexNodeErrorClass, LexNodeErrorCode, LexNodeErrorInit, } from "./errors.js";
 export type { Body, CallOptions, Data, HttpMethod, LexNodeResult, Meta, MetaExtras, MethodOf, Operation, PathParams, Query, RateLimitSnapshot, RequestArgs, RetryPolicy, } from "./types.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 type { MonitorSyncFailedPayload, MonitorSyncSucceededPayload, PeriodEndingPayload, ProcessMovementCreatedPayload, ProcessSourceIndex, PublicationCreatedPayload, PublicationHarvestCompletedPayload, PublicationTextAlertMatch, PublicationTextAlertMatchedPayload, QuotaLowPayload, SubscribableWebhookEventType, SearchJobFailedPayload, SearchJobSucceededPayload, SubscriptionPastDuePayload, SuspensionSignal, UnknownWebhookEvent, VerifyWebhookOptions, WebhookEvent, WebhookEventEnvelope, WebhookEventType, WebhookHeaders, WebhookParseRejection, WebhookParseResult, WebhookRawBody, WebhookRejection, WebhookTestPayload, WebhookVerification, } from "./webhooks.js";
+export type { MonitorSyncFailedPayload, MonitorSyncInstance, MonitorSyncSucceededPayload, PeriodEndingPayload, ProcessInstanceDiscoveredPayload, ProcessInstanceDiscoveredWithheldPayload, ProcessMovementCreatedPayload, ProcessMovementInstanceCount, ProcessSourceIndex, PublicationCreatedPayload, PublicationHarvestCompletedPayload, PublicationTextAlertMatch, PublicationTextAlertMatchedPayload, QuotaLowPayload, SubscribableWebhookEventType, SearchJobFailedPayload, SearchJobSucceededPayload, SubscriptionPastDuePayload, SuspensionSignal, UnknownWebhookEvent, VerifyWebhookOptions, WebhookEvent, WebhookEventEnvelope, WebhookEventType, WebhookHeaders, WebhookParseRejection, WebhookParseResult, WebhookRawBody, WebhookRejection, WebhookTestPayload, WebhookVerification, } from "./webhooks.js";
 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/dist/webhooks.d.ts

@@ -83,6 +83,19 @@ export interface ProcessSourceIndex {
     updatedThrough: string | null;
     checkedAt: string;
 }
+/** Quantos movimentos novos de um grau a captura anunciou. */
+export interface ProcessMovementInstanceCount {
+    /** A sigla do grau (G1, G2, JE, TR…); nula quando a fonte não a declara. */
+    degree: string | null;
+    newMovementCount: number;
+    /** A chave do movimento novo mais recente deste grau. */
+    latestMovementKey: string;
+}
+/**
+ * Um aviso por assinante e por captura do processo, descrito pelo movimento
+ * novo mais recente: o topo do payload é dele, e a chave dele é
+ * `latestMovementKey`.
+ */
 export interface ProcessMovementCreatedPayload {
     canonicalProcessId: string;
     tribunalAlias: string;
@@ -99,12 +112,82 @@ export interface ProcessMovementCreatedPayload {
      */
     latestMovementCode?: number | null;
     latestMovementLabel?: string | null;
+    /**
+     * O grau do movimento mais recente e o documento da fonte que o trouxe — o
+     * `sourceId` da instância na leitura do processo. Ausentes quando o processo
+     * não é compartilhável.
+     */
+    degree?: string | null;
+    instanceSourceId?: string | null;
+    /**
+     * Quantos movimentos novos vieram de cada grau nesta captura, o grau do mais
+     * recente primeiro. Ausente quando o processo não é compartilhável.
+     */
+    instances?: ProcessMovementInstanceCount[];
     /**
      * Presente quando o processo não é compartilhável: o aviso diz que ele andou
-     * e não diz o quê, porque ali o nome do ato é teor.
+     * e não diz o quê nem em que grau, porque ali o nome do ato é teor.
      */
     contentWithheld?: true;
 }
+/**
+ * Outro grau de um processo assinado apareceu na fonte (1º grau, 2º grau,
+ * turma recursal…). O histórico dele entrou no acervo sem virar
+ * `PROCESS_MOVEMENT_CREATED` movimento a movimento: este aviso é o que diz que
+ * ele chegou, e os movimentos estão no retrato do processo, em `instances`.
+ */
+export interface ProcessInstanceDiscoveredPayload {
+    canonicalProcessId: string;
+    tribunalAlias: string;
+    processNumber: string;
+    /** O ponteiro que o consumidor informou ao assinar o processo. */
+    externalRef: string | null;
+    /** A sigla do grau novo; nula quando a fonte não a declara. */
+    degree: string | null;
+    /** O documento da fonte deste grau — o `sourceId` dele em `instances`. */
+    instanceSourceId: string;
+    courtBody: string | null;
+    /** Quantos movimentos o grau trouxe na captura que o descobriu. */
+    movementCount: number;
+    /** Quantos deles entraram no acervo sem aviso próprio. */
+    historyMovementCount: number;
+    /**
+     * Quantos deles saíram também em `PROCESS_MOVEMENT_CREATED`: os datados
+     * depois da primeira captura do número.
+     */
+    announcedMovementCount: number;
+    /** O movimento mais recente do grau novo. */
+    latestMovementAt: string | null;
+    latestMovementCode: number | null;
+    latestMovementLabel: string | null;
+    contentWithheld?: never;
+}
+/**
+ * O mesmo aviso sobre processo não compartilhável: diz que o número ganhou um
+ * grau e não diz qual, nem o órgão, nem quantos movimentos.
+ */
+export interface ProcessInstanceDiscoveredWithheldPayload {
+    canonicalProcessId: string;
+    tribunalAlias: string;
+    processNumber: string;
+    externalRef: string | null;
+    contentWithheld: true;
+}
+/** Um grau do número como a varredura da vigília de processo o deixou. */
+export interface MonitorSyncInstance {
+    degree: string | null;
+    /** O documento da fonte deste grau — o `sourceId` dele em `instances`. */
+    instanceSourceId: string;
+    /** A instância que o topo da leitura do processo serve. */
+    primary: boolean;
+    courtBody: string | null;
+    sourceUpdatedAt: string | null;
+    latestMovementAt: string | null;
+    /** Nulo quando os movimentos deste grau nunca foram capturados. */
+    movementCount: number | null;
+    /** Desde quando a resposta completa da fonte vem sem este documento. */
+    absentSince: string | null;
+}
 export interface PublicationCreatedPayload {
     monitorId: string;
     officeId: string | null;
@@ -151,6 +234,21 @@ export interface MonitorSyncSucceededPayload {
     snapshotHash?: string;
     sourceUpdatedAt?: string | null;
     latestMovementAt?: string | null;
+    /**
+     * Vigília de processo: os graus do número e os que esta passada reconheceu
+     * como novos. Só quando o controle de confidencialidade deixa o dono do
+     * monitor ler o número inteiro.
+     */
+    instances?: MonitorSyncInstance[];
+    instancesDiscovered?: MonitorSyncInstance[];
+    /**
+     * Vigília de processo cujo número corre em segredo num grau que o dono do
+     * monitor não buscou: a passada sai sem o hash e sem as datas da fonte, e
+     * `changed` fica `false`. O dono que buscou o grau em segredo, numa conta
+     * que não aceita a proveniência, recebe a passada com `changed`, o hash e as
+     * datas, e sem `instances`.
+     */
+    contentWithheld?: true;
     /** O alvo que a fonte não indexava passou a existir nesta passada. */
     firstAppearance?: true;
     /** A vigília de aparição segue esperando o alvo entrar no índice. */
@@ -280,8 +378,8 @@ type Typed<T extends string, P> = WebhookEventEnvelope & {
     type: T;
     payload: P;
 };
-/** Os dez tipos do catálogo, discriminados por `type`. */
-export type WebhookEvent = Typed<"PROCESS_MOVEMENT_CREATED", ProcessMovementCreatedPayload> | Typed<"PUBLICATION_CREATED", PublicationCreatedPayload> | Typed<"MONITOR_SYNC_SUCCEEDED", MonitorSyncSucceededPayload> | Typed<"MONITOR_SYNC_FAILED", MonitorSyncFailedPayload> | Typed<"SEARCH_JOB_COMPLETED", SearchJobSucceededPayload | SearchJobFailedPayload> | Typed<"PUBLICATION_TEXT_ALERT_MATCHED", PublicationTextAlertMatchedPayload> | Typed<"PUBLICATION_HARVEST_COMPLETED", PublicationHarvestCompletedPayload> | Typed<"QUOTA_LOW", QuotaLowPayload> | Typed<"PERIOD_ENDING", PeriodEndingPayload> | Typed<"SUBSCRIPTION_PAST_DUE", SubscriptionPastDuePayload> | Typed<"WEBHOOK_TEST", WebhookTestPayload>;
+/** Os tipos do catálogo e a entrega de teste, discriminados por `type`. */
+export type WebhookEvent = Typed<"PROCESS_MOVEMENT_CREATED", ProcessMovementCreatedPayload> | Typed<"PROCESS_INSTANCE_DISCOVERED", ProcessInstanceDiscoveredPayload | ProcessInstanceDiscoveredWithheldPayload> | Typed<"PUBLICATION_CREATED", PublicationCreatedPayload> | Typed<"MONITOR_SYNC_SUCCEEDED", MonitorSyncSucceededPayload> | Typed<"MONITOR_SYNC_FAILED", MonitorSyncFailedPayload> | Typed<"SEARCH_JOB_COMPLETED", SearchJobSucceededPayload | SearchJobFailedPayload> | Typed<"PUBLICATION_TEXT_ALERT_MATCHED", PublicationTextAlertMatchedPayload> | Typed<"PUBLICATION_HARVEST_COMPLETED", PublicationHarvestCompletedPayload> | Typed<"QUOTA_LOW", QuotaLowPayload> | Typed<"PERIOD_ENDING", PeriodEndingPayload> | Typed<"SUBSCRIPTION_PAST_DUE", SubscriptionPastDuePayload> | Typed<"WEBHOOK_TEST", WebhookTestPayload>;
 /**
  * O evento que o catálogo ainda não descreve.
  *
@@ -304,7 +402,7 @@ export type WebhookEventType = WebhookEvent["type"];
  */
 export declare const WEBHOOK_TEST_EVENT_TYPE: "WEBHOOK_TEST";
 /** Os tipos que se pode ASSINAR ao cadastrar um endpoint. */
-export declare const WEBHOOK_EVENT_TYPES: readonly ["PROCESS_MOVEMENT_CREATED", "PUBLICATION_CREATED", "MONITOR_SYNC_SUCCEEDED", "MONITOR_SYNC_FAILED", "SEARCH_JOB_COMPLETED", "PUBLICATION_TEXT_ALERT_MATCHED", "PUBLICATION_HARVEST_COMPLETED", "QUOTA_LOW", "PERIOD_ENDING", "SUBSCRIPTION_PAST_DUE"];
+export declare const WEBHOOK_EVENT_TYPES: readonly ["PROCESS_MOVEMENT_CREATED", "PROCESS_INSTANCE_DISCOVERED", "PUBLICATION_CREATED", "MONITOR_SYNC_SUCCEEDED", "MONITOR_SYNC_FAILED", "SEARCH_JOB_COMPLETED", "PUBLICATION_TEXT_ALERT_MATCHED", "PUBLICATION_HARVEST_COMPLETED", "QUOTA_LOW", "PERIOD_ENDING", "SUBSCRIPTION_PAST_DUE"];
 /**
  * O que entra em `eventTypes` ao cadastrar um endpoint. É subconjunto próprio
  * de `WebhookEventType`: mandar a entrega de teste nessa lista é recusa.

package/dist/webhooks.js

@@ -117,6 +117,7 @@ export const WEBHOOK_TEST_EVENT_TYPE = "WEBHOOK_TEST";
 /** Os tipos que se pode ASSINAR ao cadastrar um endpoint. */
 export const WEBHOOK_EVENT_TYPES = [
     "PROCESS_MOVEMENT_CREATED",
+    "PROCESS_INSTANCE_DISCOVERED",
     "PUBLICATION_CREATED",
     "MONITOR_SYNC_SUCCEEDED",
     "MONITOR_SYNC_FAILED",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexnode/legal-data-sdk",
-  "version": "1.25.0",
+  "version": "1.27.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

@@ -139,7 +139,7 @@ export interface paths {
         put?: never;
         /**
          * Buscar processos
-         * @description Executa uma busca estruturada de processos em um tribunal suportado. A consulta por número completo é atendida lake-first (sem chamada ao upstream enquanto o dado está fresco); todo hit vivo é gravado de volta no data lake. No modo assíncrono o endpoint responde 202 com um descritor de job — consulte o resultado em GET /v1/search-jobs/{jobId}. **Antes de concluir que um processo não existe, leia `sourceIndex.updatedThrough`:** é a data até onde o índice do tribunal está atualizado. Um processo distribuído depois dela ainda não é encontrável, e `total: 0` ali significa *ainda não chegou*, não *não existe*. O campo acompanha toda resposta que consulta a fonte, sem custo adicional.
+         * @description Executa uma busca estruturada de processos em um tribunal suportado. A consulta por número completo é atendida lake-first (sem chamada ao upstream enquanto o dado está fresco), com um item por documento que a fonte ainda traz do número, a principal primeiro; quando eles não cabem em `limit`, a consulta vai à fonte, que pagina. Todo hit vivo é gravado de volta no data lake, cada documento na sua instância. No modo assíncrono o endpoint responde 202 com um descritor de job — consulte o resultado em GET /v1/search-jobs/{jobId}. **Antes de concluir que um processo não existe, leia `sourceIndex.updatedThrough`:** é a data até onde o índice do tribunal está atualizado. Um processo distribuído depois dela ainda não é encontrável, e `total: 0` ali significa *ainda não chegou*, não *não existe*. O campo acompanha toda resposta que consulta a fonte, sem custo adicional.
          *
          *     **Escopo exigido na chave de API:** `PROCESSES_SEARCH`
          */
@@ -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; 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.
+         * @description Retorna o registro exato do processo para o tribunal e o número informados, com resolução cache-first quando disponível. **Um número, várias instâncias.** A fonte guarda um documento por instância do processo (1º grau, 2º grau, turma recursal…), às vezes dois do mesmo grau, e o motor guarda cada um na sua instância. O topo da resposta é sempre a instância principal do número — a mesma de uma leitura para a outra, que só muda quando uma resposta completa da fonte deixa de trazê-la —, com o grau em `degree`, e `data.instances` lista todos os documentos, a principal primeiro, cada um com `origin` (`SOURCE` quando veio da fonte nesta resposta, `LAKE` quando saiu do acervo), `fetchedAt` e `absentSince`. Todos levam a classificação do número inteiro: basta um documento em segredo de justiça para todos saírem marcados. `meta.sourceFetchedAt` diz quando os dados do topo foram buscados na fonte; a ficha retida pelo controle de confidencialidade, sem o teor, não o traz nem lista as instâncias. `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`): o documento que o acervo já guardava e não veio sai em `data.instances` do acervo, com a data dele, e outra instância que o acervo não conhece, se existir, pode não ter vindo. Resposta parcial sem o processo é 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. `meta.otherInstances` resume os outros documentos do número que vieram na resposta, além da principal: 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. A cópia é montada por instância, cada uma com a data dela em `data.instances[].fetchedAt`, e o número que a resposta completa mais recente da fonte já não trazia em documento nenhum não é socorrido. 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; 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.
+         * @description Busca o processo na fonte processual e retorna o registro normalizado do processo, o payload bruto da fonte e as movimentações normalizadas. **Um número, várias instâncias.** A fonte guarda um documento por instância do processo (1º grau, 2º grau, turma recursal…), às vezes dois do mesmo grau, e o motor guarda cada um na sua instância. O topo da resposta é sempre a instância principal do número — a mesma de uma leitura para a outra, que só muda quando uma resposta completa da fonte deixa de trazê-la —, com o grau em `degree`, e `data.instances` lista todos os documentos, a principal primeiro, cada um com `origin` (`SOURCE` quando veio da fonte nesta resposta, `LAKE` quando saiu do acervo), `fetchedAt` e `absentSince`. Todos levam a classificação do número inteiro: basta um documento em segredo de justiça para todos saírem marcados. `meta.sourceFetchedAt` diz quando os dados do topo foram buscados na fonte; a ficha retida pelo controle de confidencialidade, sem o teor, não o traz nem lista as instâncias. `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`): o documento que o acervo já guardava e não veio sai em `data.instances` do acervo, com a data dele, e outra instância que o acervo não conhece, se existir, pode não ter vindo. Resposta parcial sem o processo é 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. `meta.otherInstances` resume os outros documentos do número que vieram na resposta, além da principal: 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. A cópia é montada por instância, cada uma com a data dela em `data.instances[].fetchedAt`, e o número que a resposta completa mais recente da fonte já não trazia em documento nenhum não é socorrido. 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. `process` e `movements` são os da instância principal, e cada entrada de `data.instances` traz os movimentos da última captura dela, do mais recente ao mais antigo; na instância cujos movimentos o motor nunca capturou, `movements` e `movementCount` são nulos, nunca lista vazia. A resposta parcial sem a instância principal serve a principal do acervo, e é 502 `UPSTREAM_UNAVAILABLE` quando o acervo não guarda os movimentos dela. No retrato socorrido pelo acervo, os movimentos e o registro de cada instância são os da última captura guardada dela — o socorro exige a da principal —, e `sourcePayload` é nulo: o documento bruto da fonte não é guardado.
          *
          *     **Escopo exigido na chave de API:** `PROCESSES_READ`
          */
@@ -225,7 +225,7 @@ export interface paths {
         };
         /**
          * Listar as movimentações em cache do processo
-         * @description Retorna as movimentações em cache de um número de processo no tribunal informado. Esta rota não busca movimentações no upstream sob demanda.
+         * @description Retorna as movimentações em cache de um número de processo no tribunal informado. Esta rota não busca movimentações no upstream sob demanda. Cada item diz em `degrees` o grau (ou os graus) cujo documento o trouxe na última captura — vazio no movimento que nenhuma captura atual traz —, e `degree` recorta a lista por grau.
          *
          *     **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. O `process` e os `movements` do item são os da instância principal do número, e `snapshot.instances` lista os documentos do número só com o cabeçalho. 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`
          */
@@ -397,7 +397,7 @@ export interface paths {
         };
         /**
          * Consultar um job de busca
-         * @description Retorna o status do job; em SUCCEEDED, `result` carrega o mesmo formato da busca síncrona de processos — inclusive `sourceIndex.updatedThrough`, a data até onde o índice do tribunal está atualizado, que qualifica um `total: 0` como *ainda não chegou* em vez de *não existe*. O campo acompanha o resultado que consultou a fonte; um job servido do acervo não o traz. Jobs são visíveis apenas para a conta/office que os submeteu (404 caso contrário). A submissão acontece via POST /v1/processes/search, que responde 202 + jobId quando o modo assíncrono está ativo.
+         * @description Retorna o status do job; em SUCCEEDED, `result` carrega o mesmo formato da busca síncrona de processos — inclusive `sourceIndex.updatedThrough`, a data até onde o índice do tribunal está atualizado, que qualifica um `total: 0` como *ainda não chegou* em vez de *não existe*. O campo acompanha o resultado que consultou a fonte; um job servido do acervo não o traz. O processo que o controle de confidencialidade retém de quem consulta sai de `items`, conta em `redactedCount` e uma vez só em `total`, quantos documentos dele a busca tenha achado. Jobs são visíveis apenas para a conta/office que os submeteu (404 caso contrário). A submissão acontece via POST /v1/processes/search, que responde 202 + jobId quando o modo assíncrono está ativo.
          *
          *     **Escopo exigido na chave de API:** `PROCESSES_READ`
          */
@@ -449,7 +449,7 @@ export interface paths {
         put?: never;
         /**
          * Registrar interesse durável em um processo
-         * @description Concede uma assinatura CASE_LINK para que o motor mantenha o processo atualizado e emita `PROCESS_MOVEMENT_CREATED` aos endpoints da conta a cada movimentação nova. Idempotente por (reason, externalRef).
+         * @description Concede uma assinatura CASE_LINK para que o motor mantenha o processo atualizado e emita `PROCESS_MOVEMENT_CREATED` aos endpoints da conta a cada movimentação nova, e `PROCESS_INSTANCE_DISCOVERED` quando outro grau do número aparece na fonte. Idempotente por (reason, externalRef).
          *
          *     **Escopo exigido na chave de API:** `SUBSCRIPTIONS_WRITE`
          */
@@ -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. */
@@ -2116,13 +2118,91 @@ export interface operations {
                                 latestPublicationExcerpt?: string | null;
                                 latestPublicationUrl?: string | null;
                             } | null;
+                            /** @description Todos os documentos que o motor guarda deste número — em geral um por instância (1º grau, 2º grau, turma recursal…), às vezes dois do mesmo grau —, a principal primeiro, depois os que a fonte ainda traz e por fim os que ela deixou de trazer. O topo da resposta é a principal. Cada um leva a classificação do número inteiro: basta um documento em segredo de justiça para todos saírem marcados. Ausente na ficha que o controle de confidencialidade entrega retida, sem o teor. */
+                            instances?: {
+                                sourceId?: string | null;
+                                number: string;
+                                formattedNumber: string;
+                                tribunal: {
+                                    alias: string;
+                                    code: string;
+                                };
+                                degree?: string | null;
+                                sigiloLevel?: number | null;
+                                /**
+                                 * @description Classificação do motor: PUBLIC ou SEGREDO_DE_JUSTICA. Linha em segredo nunca deve ser exibida a público.
+                                 * @enum {string}
+                                 */
+                                confidentiality?: "PUBLIC" | "SEGREDO_DE_JUSTICA";
+                                /** @description Se a linha pode ser amortizada entre consumidores. Falso acompanha o segredo e também a linha que o motor reteve por outro motivo. */
+                                shareable?: boolean;
+                                class: {
+                                    code?: number | null;
+                                    name?: string | null;
+                                } | null;
+                                courtBody: {
+                                    code?: number | null;
+                                    name?: string | null;
+                                    municipalityIbgeCode?: number | null;
+                                } | null;
+                                system?: {
+                                    code?: number | null;
+                                    name?: string | null;
+                                } | null;
+                                format?: {
+                                    code?: number | null;
+                                    name?: string | null;
+                                } | null;
+                                /** Format: date-time */
+                                filedAt?: string | null;
+                                /** Format: date-time */
+                                updatedAt?: string | null;
+                                /** Format: date-time */
+                                indexedAt?: string | null;
+                                subjects: {
+                                    code?: number | null;
+                                    name: string;
+                                }[];
+                                /** @description A instância principal do número, a que o topo da resposta serve. É a mesma de uma leitura para a outra e só muda quando uma resposta completa da fonte pelo número deixa de trazê-la. */
+                                primary: boolean;
+                                /**
+                                 * @description `SOURCE`: veio da fonte nesta resposta. `LAKE`: servida do que o acervo guarda — a fonte não a trouxe nesta resposta, ou a resposta inteira saiu do acervo.
+                                 * @enum {string}
+                                 */
+                                origin: "SOURCE" | "LAKE";
+                                /**
+                                 * Format: date-time
+                                 * @description Quando os dados desta instância foram buscados na fonte. No retrato, com os movimentos servidos do acervo, é a data da captura deles.
+                                 */
+                                fetchedAt: string;
+                                /**
+                                 * Format: date-time
+                                 * @description Desde quando a resposta completa da fonte pelo número vem sem este documento; nulo enquanto ela o traz.
+                                 */
+                                absentSince: string | null;
+                            }[];
                         };
                         meta: {
                             /** @description Identificador da requisição, para suporte e rastreamento. É o X-Request-Id enviado pelo cliente quando há um; senão, um req_<uuid> cunhado pelo motor. */
                             requestId: string;
                             credits?: number;
                             cacheHit?: boolean;
-                            /** @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. */
+                            /**
+                             * 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: o documento que o acervo já guardava e não veio sai em `instances` do acervo (`origin: LAKE`), e outra instância que o acervo não conhece, se existir, pode não ter vindo. */
                             partialIndex?: {
                                 /** @description Partes do índice da fonte que não responderam. */
                                 shardsFailed: number;
@@ -2131,7 +2211,7 @@ 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. */
+                            /** @description Presente só quando a resposta da fonte trouxe outros documentos do número além da instância principal, que é o topo de `data` (com o grau em `degree`) — em geral de instâncias diferentes, mas dois podem ter o mesmo `grau`. O motor guarda cada documento na sua instância e serve todos em `data.instances`; esta lista é o resumo dos 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;
@@ -2676,6 +2756,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. */
@@ -2761,13 +2843,104 @@ export interface operations {
                                 complementos: unknown;
                                 rawPayload: unknown;
                             }[];
+                            /** @description Todos os documentos que o motor guarda deste número — em geral um por instância (1º grau, 2º grau, turma recursal…), às vezes dois do mesmo grau —, a principal primeiro, depois os que a fonte ainda traz e por fim os que ela deixou de trazer. O topo da resposta é a principal. Cada um leva a classificação do número inteiro: basta um documento em segredo de justiça para todos saírem marcados. `process` e `movements` são os da principal, e cada instância traz os movimentos dela. */
+                            instances: {
+                                sourceId?: string | null;
+                                number: string;
+                                formattedNumber: string;
+                                tribunal: {
+                                    alias: string;
+                                    code: string;
+                                };
+                                degree?: string | null;
+                                sigiloLevel?: number | null;
+                                /**
+                                 * @description Classificação do motor: PUBLIC ou SEGREDO_DE_JUSTICA. Linha em segredo nunca deve ser exibida a público.
+                                 * @enum {string}
+                                 */
+                                confidentiality?: "PUBLIC" | "SEGREDO_DE_JUSTICA";
+                                /** @description Se a linha pode ser amortizada entre consumidores. Falso acompanha o segredo e também a linha que o motor reteve por outro motivo. */
+                                shareable?: boolean;
+                                class: {
+                                    code?: number | null;
+                                    name?: string | null;
+                                } | null;
+                                courtBody: {
+                                    code?: number | null;
+                                    name?: string | null;
+                                    municipalityIbgeCode?: number | null;
+                                } | null;
+                                system?: {
+                                    code?: number | null;
+                                    name?: string | null;
+                                } | null;
+                                format?: {
+                                    code?: number | null;
+                                    name?: string | null;
+                                } | null;
+                                /** Format: date-time */
+                                filedAt?: string | null;
+                                /** Format: date-time */
+                                updatedAt?: string | null;
+                                /** Format: date-time */
+                                indexedAt?: string | null;
+                                subjects: {
+                                    code?: number | null;
+                                    name: string;
+                                }[];
+                                /** @description A instância principal do número, a que o topo da resposta serve. É a mesma de uma leitura para a outra e só muda quando uma resposta completa da fonte pelo número deixa de trazê-la. */
+                                primary: boolean;
+                                /**
+                                 * @description `SOURCE`: veio da fonte nesta resposta. `LAKE`: servida do que o acervo guarda — a fonte não a trouxe nesta resposta, ou a resposta inteira saiu do acervo.
+                                 * @enum {string}
+                                 */
+                                origin: "SOURCE" | "LAKE";
+                                /**
+                                 * Format: date-time
+                                 * @description Quando os dados desta instância foram buscados na fonte. No retrato, com os movimentos servidos do acervo, é a data da captura deles.
+                                 */
+                                fetchedAt: string;
+                                /**
+                                 * Format: date-time
+                                 * @description Desde quando a resposta completa da fonte pelo número vem sem este documento; nulo enquanto ela o traz.
+                                 */
+                                absentSince: string | null;
+                                /** @description Se o motor guarda os movimentos desta instância. Falso quando eles nunca foram capturados — o documento só veio numa ficha ou numa busca — ou quando o acervo já não guarda algum deles, e aí `movements` e `movementCount` são nulos. */
+                                movementsCaptured: boolean;
+                                /** @description Quantos movimentos a última captura desta instância trouxe; nulo quando eles nunca foram capturados. */
+                                movementCount: number | null;
+                                /** @description Os movimentos da última captura desta instância, do mais recente ao mais antigo, sem o payload bruto da fonte; nulo quando eles nunca foram capturados. */
+                                movements: {
+                                    externalMovementKey: string;
+                                    codigo?: number | null;
+                                    nome: string;
+                                    /** Format: date-time */
+                                    dataHora?: string | null;
+                                    complementos: unknown;
+                                }[] | null;
+                            }[];
                         };
                         meta: {
                             /** @description Identificador da requisição, para suporte e rastreamento. É o X-Request-Id enviado pelo cliente quando há um; senão, um req_<uuid> cunhado pelo motor. */
                             requestId: string;
                             credits?: number;
                             cacheHit?: boolean;
-                            /** @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. */
+                            /**
+                             * 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: o documento que o acervo já guardava e não veio sai em `instances` do acervo (`origin: LAKE`), e outra instância que o acervo não conhece, se existir, pode não ter vindo. */
                             partialIndex?: {
                                 /** @description Partes do índice da fonte que não responderam. */
                                 shardsFailed: number;
@@ -2776,7 +2949,7 @@ 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. */
+                            /** @description Presente só quando a resposta da fonte trouxe outros documentos do número além da instância principal, que é o topo de `data` (com o grau em `degree`) — em geral de instâncias diferentes, mas dois podem ter o mesmo `grau`. O motor guarda cada documento na sua instância e serve todos em `data.instances`; esta lista é o resumo dos 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;
@@ -3011,6 +3184,8 @@ export interface operations {
             query: {
                 tribunalAlias: string;
                 since?: unknown;
+                /** @description Só os movimentos que o documento deste grau (G1, G2, JE, TR…) trouxe na última captura, sem distinguir maiúsculas. O grau sem movimento guardado responde lista vazia. */
+                degree?: string;
             };
             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. */
@@ -3040,6 +3215,8 @@ export interface operations {
                                 formattedProcessNumber: string;
                                 /** Format: date-time */
                                 movementDate?: string | null;
+                                /** @description Os graus (G1, G2, JE, TR…) cujo documento trouxe este movimento na última captura. Em geral um; dois quando o mesmo ato está nos dois documentos do número. Vazio quando nenhuma captura atual o traz. */
+                                degrees: string[];
                                 code: number | null;
                                 label?: string | null;
                                 payload: unknown;
@@ -3361,6 +3538,84 @@ export interface operations {
                                         } | null;
                                     };
                                     movements: unknown[];
+                                    /** @description Os documentos que o motor guarda do número, a principal primeiro, só com o cabeçalho de cada um: os movimentos de cada instância vêm no retrato de um processo. */
+                                    instances: {
+                                        sourceId?: string | null;
+                                        number: string;
+                                        formattedNumber: string;
+                                        tribunal: {
+                                            alias: string;
+                                            code: string;
+                                        };
+                                        degree?: string | null;
+                                        sigiloLevel?: number | null;
+                                        /**
+                                         * @description Classificação do motor: PUBLIC ou SEGREDO_DE_JUSTICA. Linha em segredo nunca deve ser exibida a público.
+                                         * @enum {string}
+                                         */
+                                        confidentiality?: "PUBLIC" | "SEGREDO_DE_JUSTICA";
+                                        /** @description Se a linha pode ser amortizada entre consumidores. Falso acompanha o segredo e também a linha que o motor reteve por outro motivo. */
+                                        shareable?: boolean;
+                                        class: {
+                                            code?: number | null;
+                                            name?: string | null;
+                                        } | null;
+                                        courtBody: {
+                                            code?: number | null;
+                                            name?: string | null;
+                                            municipalityIbgeCode?: number | null;
+                                        } | null;
+                                        system?: {
+                                            code?: number | null;
+                                            name?: string | null;
+                                        } | null;
+                                        format?: {
+                                            code?: number | null;
+                                            name?: string | null;
+                                        } | null;
+                                        /** Format: date-time */
+                                        filedAt?: string | null;
+                                        /** Format: date-time */
+                                        updatedAt?: string | null;
+                                        /** Format: date-time */
+                                        indexedAt?: string | null;
+                                        subjects: {
+                                            code?: number | null;
+                                            name: string;
+                                        }[];
+                                        /** @description A instância principal do número, a que o topo da resposta serve. É a mesma de uma leitura para a outra e só muda quando uma resposta completa da fonte pelo número deixa de trazê-la. */
+                                        primary: boolean;
+                                        /**
+                                         * @description `SOURCE`: veio da fonte nesta resposta. `LAKE`: servida do que o acervo guarda — a fonte não a trouxe nesta resposta, ou a resposta inteira saiu do acervo.
+                                         * @enum {string}
+                                         */
+                                        origin: "SOURCE" | "LAKE";
+                                        /**
+                                         * Format: date-time
+                                         * @description Quando os dados desta instância foram buscados na fonte. No retrato, com os movimentos servidos do acervo, é a data da captura deles.
+                                         */
+                                        fetchedAt: string;
+                                        /**
+                                         * Format: date-time
+                                         * @description Desde quando a resposta completa da fonte pelo número vem sem este documento; nulo enquanto ela o traz.
+                                         */
+                                        absentSince: string | null;
+                                    }[];
+                                };
+                                /** @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;
@@ -11838,7 +12093,7 @@ export interface operations {
                             windowDays: number;
                             items: ({
                                 /** @enum {string} */
-                                type: "PROCESS_MOVEMENT_CREATED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE";
+                                type: "PROCESS_MOVEMENT_CREATED" | "PROCESS_INSTANCE_DISCOVERED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE";
                                 /** @enum {string} */
                                 class: "DATA" | "OPERATIONAL";
                                 count: number;
@@ -11849,7 +12104,7 @@ export interface operations {
                             })[];
                             dismissed: ({
                                 /** @enum {string} */
-                                type: "PROCESS_MOVEMENT_CREATED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE";
+                                type: "PROCESS_MOVEMENT_CREATED" | "PROCESS_INSTANCE_DISCOVERED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE";
                                 /** Format: date-time */
                                 dismissedAt: string;
                             } & {
@@ -12054,7 +12309,7 @@ export interface operations {
             query?: {
                 cursor?: string;
                 limit?: number;
-                type?: "PROCESS_MOVEMENT_CREATED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE";
+                type?: "PROCESS_MOVEMENT_CREATED" | "PROCESS_INSTANCE_DISCOVERED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE";
                 monitorId?: string;
                 since?: unknown;
                 until?: unknown;
@@ -12807,7 +13062,7 @@ export interface operations {
                     /** Format: uri */
                     url: string;
                     description?: string;
-                    eventTypes: ("PROCESS_MOVEMENT_CREATED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE")[];
+                    eventTypes: ("PROCESS_MOVEMENT_CREATED" | "PROCESS_INSTANCE_DISCOVERED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE")[];
                     /** @default true */
                     isActive?: boolean;
                 };
@@ -13282,7 +13537,7 @@ export interface operations {
                     /** Format: uri */
                     url?: string;
                     description?: string;
-                    eventTypes?: ("PROCESS_MOVEMENT_CREATED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE")[];
+                    eventTypes?: ("PROCESS_MOVEMENT_CREATED" | "PROCESS_INSTANCE_DISCOVERED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE")[];
                     isActive?: boolean;
                 };
             };
@@ -13975,7 +14230,7 @@ export interface operations {
                     from: unknown;
                     to?: unknown;
                     /** @enum {string} */
-                    type?: "PROCESS_MOVEMENT_CREATED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE";
+                    type?: "PROCESS_MOVEMENT_CREATED" | "PROCESS_INSTANCE_DISCOVERED" | "PUBLICATION_CREATED" | "MONITOR_SYNC_SUCCEEDED" | "MONITOR_SYNC_FAILED" | "SEARCH_JOB_COMPLETED" | "PUBLICATION_TEXT_ALERT_MATCHED" | "PUBLICATION_HARVEST_COMPLETED" | "QUOTA_LOW" | "PERIOD_ENDING" | "SUBSCRIPTION_PAST_DUE";
                     /** @default false */
                     includeDelivered?: boolean;
                 };