@baruk/core 0.4.2 → 0.6.0

package/dist/platform/capabilities.d.ts

@@ -0,0 +1,88 @@
+/**
+ * O contrato de CAPACIDADE entre a API e as telas que a consomem.
+ *
+ * ## O defeito que isto existe para fechar
+ *
+ * O console publica na Vercel no instante do merge. A API publica na Render
+ * depois — build da imagem, `db:predeploy`, health check. Entre um e outro
+ * existe uma janela de minutos em que o navegador carrega a tela NOVA e fala
+ * com a API VELHA. Na Onda A isso não foi hipótese: nove rotas
+ * (`/v1/tenant/profile`, `/v1/tenant/features`, `/v1/tenant/setup`,
+ * `/v1/fiscal/governance` e as irmãs) existiram na tela antes de existirem no
+ * servidor.
+ *
+ * O que a pessoa via nessa janela era a pior variante possível: um 404 da API
+ * que o Next transforma em tela genérica de erro, com `digest` e pedido de
+ * abrir chamado — o mesmo modo de falha que o `SemAcesso` corrigiu para RBAC.
+ * Não é erro do sistema: é uma versão que ainda não subiu.
+ *
+ * ## Por que capacidade, e não SHA
+ *
+ * Comparar o commit servido com o commit esperado acopla a tela ao processo de
+ * release: qualquer publicação — inclusive uma que não muda nada relevante —
+ * passa a poder derrubar a tela, e um hotfix na API com outro SHA reprovaria
+ * um frontend perfeitamente compatível. O que a tela precisa saber não é QUAL
+ * build está no ar, e sim se aquele build SABE responder o que ela vai pedir.
+ *
+ * Por isso o contrato é uma lista de nomes. A API declara o que serve; a tela
+ * declara o que exige. Compatibilidade é continência de conjunto, não
+ * igualdade de versão — e é isso que torna o backend-first possível: a API
+ * publica a capacidade ANTES da tela existir, e nada quebra porque ninguém
+ * ainda a exige.
+ *
+ * ## Regras de evolução
+ *
+ * - Uma chave é imutável. Mudança incompatível ganha `.v2`; a `.v1` só sai
+ *   quando nenhum frontend em produção ainda a exigir.
+ * - A API nunca declara capacidade que não implementa — o guarda
+ *   `capabilities.test.ts` confere cada rota declarada contra as rotas
+ *   efetivamente montadas no Fastify. Declarar sem implementar seria o mesmo
+ *   defeito de novo, com um passo a mais de indireção.
+ * - Ausência é resposta legítima. A tela degrada para "aguardando a API", não
+ *   para erro.
+ */
+/**
+ * Versão do FORMATO da resposta de `/v1/capabilities` — não das capacidades.
+ *
+ * Muda apenas se a forma do documento mudar. Um cliente que não reconhece a
+ * versão trata tudo como indisponível: fail-closed é a única leitura segura de
+ * um contrato que não se sabe ler.
+ */
+export declare const CAPABILITY_CONTRACT_VERSION = 1;
+export interface ApiCapabilityDef {
+    /** `<produto>.<recurso>.v<N>`. Imutável depois de publicada. */
+    key: string;
+    label: string;
+    /**
+     * Rotas que compõem a capacidade, no formato do Fastify (`/v1/x/:id`).
+     *
+     * Não é documentação: é o que o guarda executa. Uma capacidade cujas rotas
+     * não existem no app montado reprova o build.
+     */
+    routes: readonly string[];
+}
+/**
+ * O que ESTE build da API serve.
+ *
+ * A Onda A entra inteira porque foi ela quem sofreu o skew. Capacidades
+ * anteriores não estão aqui de propósito: uma tela que nunca conheceu janela
+ * de incompatibilidade não ganha um portão novo para atravessar.
+ */
+export declare const API_CAPABILITIES: readonly ApiCapabilityDef[];
+export declare const API_CAPABILITY_KEYS: readonly string[];
+/** Formato exigido de uma chave. O guarda usa isto; a revisão humana não basta. */
+export declare const CAPABILITY_KEY_PATTERN: RegExp;
+export interface CapabilityDocument {
+    contract: number;
+    capabilities: readonly string[];
+}
+/**
+ * A API declarada satisfaz o que a tela exige?
+ *
+ * Fail-closed em três frentes, e todas já aconteceram em produção em algum
+ * produto: documento ausente (API velha, sem a rota), versão de contrato
+ * desconhecida (cliente novo demais ou velho demais) e capacidade faltando.
+ * Nenhuma delas devolve "sim por não saber".
+ */
+export declare function satisfiesCapability(doc: CapabilityDocument | null | undefined, required: string): boolean;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/platform/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/platform/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,gBAAgB,EA8FvD,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAuC,CAAC;AAEzF,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,QACgC,CAAC;AAEpE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,kBAAkB,GAAG,IAAI,GAAG,SAAS,EAC1C,QAAQ,EAAE,MAAM,GACf,OAAO,CAIT"}

package/dist/platform/capabilities.js

@@ -0,0 +1,169 @@
+/**
+ * O contrato de CAPACIDADE entre a API e as telas que a consomem.
+ *
+ * ## O defeito que isto existe para fechar
+ *
+ * O console publica na Vercel no instante do merge. A API publica na Render
+ * depois — build da imagem, `db:predeploy`, health check. Entre um e outro
+ * existe uma janela de minutos em que o navegador carrega a tela NOVA e fala
+ * com a API VELHA. Na Onda A isso não foi hipótese: nove rotas
+ * (`/v1/tenant/profile`, `/v1/tenant/features`, `/v1/tenant/setup`,
+ * `/v1/fiscal/governance` e as irmãs) existiram na tela antes de existirem no
+ * servidor.
+ *
+ * O que a pessoa via nessa janela era a pior variante possível: um 404 da API
+ * que o Next transforma em tela genérica de erro, com `digest` e pedido de
+ * abrir chamado — o mesmo modo de falha que o `SemAcesso` corrigiu para RBAC.
+ * Não é erro do sistema: é uma versão que ainda não subiu.
+ *
+ * ## Por que capacidade, e não SHA
+ *
+ * Comparar o commit servido com o commit esperado acopla a tela ao processo de
+ * release: qualquer publicação — inclusive uma que não muda nada relevante —
+ * passa a poder derrubar a tela, e um hotfix na API com outro SHA reprovaria
+ * um frontend perfeitamente compatível. O que a tela precisa saber não é QUAL
+ * build está no ar, e sim se aquele build SABE responder o que ela vai pedir.
+ *
+ * Por isso o contrato é uma lista de nomes. A API declara o que serve; a tela
+ * declara o que exige. Compatibilidade é continência de conjunto, não
+ * igualdade de versão — e é isso que torna o backend-first possível: a API
+ * publica a capacidade ANTES da tela existir, e nada quebra porque ninguém
+ * ainda a exige.
+ *
+ * ## Regras de evolução
+ *
+ * - Uma chave é imutável. Mudança incompatível ganha `.v2`; a `.v1` só sai
+ *   quando nenhum frontend em produção ainda a exigir.
+ * - A API nunca declara capacidade que não implementa — o guarda
+ *   `capabilities.test.ts` confere cada rota declarada contra as rotas
+ *   efetivamente montadas no Fastify. Declarar sem implementar seria o mesmo
+ *   defeito de novo, com um passo a mais de indireção.
+ * - Ausência é resposta legítima. A tela degrada para "aguardando a API", não
+ *   para erro.
+ */
+/**
+ * Versão do FORMATO da resposta de `/v1/capabilities` — não das capacidades.
+ *
+ * Muda apenas se a forma do documento mudar. Um cliente que não reconhece a
+ * versão trata tudo como indisponível: fail-closed é a única leitura segura de
+ * um contrato que não se sabe ler.
+ */
+export const CAPABILITY_CONTRACT_VERSION = 1;
+/**
+ * O que ESTE build da API serve.
+ *
+ * A Onda A entra inteira porque foi ela quem sofreu o skew. Capacidades
+ * anteriores não estão aqui de propósito: uma tela que nunca conheceu janela
+ * de incompatibilidade não ganha um portão novo para atravessar.
+ */
+export const API_CAPABILITIES = [
+    {
+        key: 'office.tenant-profile.v1',
+        label: 'Identificação do escritório (razão social, CNPJ, fuso)',
+        routes: ['GET /v1/tenant/profile', 'PUT /v1/tenant/profile'],
+    },
+    {
+        key: 'office.tenant-branding.v1',
+        label: 'Marca do escritório',
+        routes: ['GET /v1/tenant/branding', 'PUT /v1/tenant/branding'],
+    },
+    {
+        key: 'office.tenant-features.v1',
+        label: 'Módulos ligados e desligados pelo próprio escritório',
+        routes: ['GET /v1/tenant/features', 'PUT /v1/tenant/features'],
+    },
+    {
+        key: 'office.tenant-setup.v1',
+        label: 'Progresso de configuração do escritório',
+        routes: ['GET /v1/tenant/setup'],
+    },
+    {
+        key: 'office.fiscal-governance.v1',
+        label: 'Governança do catálogo fiscal (fonte oficial e conferência)',
+        routes: [
+            'GET /v1/fiscal/governance',
+            'PUT /v1/fiscal/rules/:id/source',
+            'POST /v1/fiscal/rules/:id/validate',
+        ],
+    },
+    {
+        key: 'office.fiscal-documents.v1',
+        label: 'Documentos fiscais capturados e o estado da sincronização',
+        routes: [
+            'GET /v1/fiscal/documents',
+            'GET /v1/fiscal/documents/:id',
+            'GET /v1/fiscal/sync-state',
+        ],
+    },
+    {
+        key: 'office.fiscal-operations.v1',
+        label: 'Motor operacional fiscal: estado por cliente, cobertura, fila humana e caixa de entrada',
+        routes: [
+            'GET /v1/fiscal/sync-clients',
+            'GET /v1/fiscal/coverage',
+            'GET /v1/fiscal/interventions',
+            'GET /v1/fiscal/metrics',
+            'GET /v1/fiscal/inbox',
+            'POST /v1/fiscal/inbox/:id/reprocess',
+            'GET /v1/fiscal/request-coverage',
+        ],
+    },
+    {
+        // Separada de `fiscal-operations` de propósito: ela não descreve a carteira
+        // do escritório, e sim o CONTRATO com o provedor oficial. Um console que
+        // exiba "transporte real desativado" antes de a rota existir mostraria a
+        // tela genérica de erro em vez do estado — que é exatamente o modo de falha
+        // que o portão de capacidade existe para fechar.
+        key: 'office.fiscal-provider-contract.v1',
+        label: 'Contrato do provedor fiscal oficial: versão, fontes e por que o transporte real está fechado',
+        routes: ['GET /v1/fiscal/provider-contract'],
+    },
+    {
+        // Declarada pela migration 0061, e exigida pela tela de cadastro.
+        //
+        // Sem o portão, um console novo contra uma API velha chamaria
+        // `availability`, receberia 404 e mostraria erro de sistema no lugar de um
+        // formulário que funciona perfeitamente sem consulta nenhuma. O cadastro
+        // manual é o caminho completo; a consulta é o atalho.
+        key: 'office.client-registry-provenance.v1',
+        label: 'Cadastro de cliente por CNPJ a partir de fonte oficial, com proveniência por atributo',
+        routes: [
+            'GET /v1/client-registry/availability',
+            'POST /v1/client-registry/lookup',
+            'POST /v1/clients/:id/registry-apply',
+            'GET /v1/clients/:id/registry-diff',
+        ],
+    },
+    {
+        // Declarada pela 0062. A tela de credenciais fiscais depende dela para
+        // mostrar matrícula e habilitação ao lado do botão bloqueado — sem isso,
+        // um console novo contra uma API velha chamaria a rota, tomaria 404 e
+        // mostraria erro de sistema no lugar de "cliente não matriculado".
+        key: 'office.fiscal-first-contact.v1',
+        label: 'Primeiro contato fiscal: matrícula do cliente, habilitação do escritório e a autorização que aceita credencial válida só localmente',
+        routes: [
+            'GET /v1/clients/:id/fiscal-enrollment',
+            'PUT /v1/clients/:id/fiscal-enrollment',
+            'PUT /v1/tenant/fiscal-automation',
+        ],
+    },
+];
+export const API_CAPABILITY_KEYS = API_CAPABILITIES.map((c) => c.key);
+/** Formato exigido de uma chave. O guarda usa isto; a revisão humana não basta. */
+export const CAPABILITY_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)+\.v\d+$/;
+/**
+ * A API declarada satisfaz o que a tela exige?
+ *
+ * Fail-closed em três frentes, e todas já aconteceram em produção em algum
+ * produto: documento ausente (API velha, sem a rota), versão de contrato
+ * desconhecida (cliente novo demais ou velho demais) e capacidade faltando.
+ * Nenhuma delas devolve "sim por não saber".
+ */
+export function satisfiesCapability(doc, required) {
+    if (!doc)
+        return false;
+    if (doc.contract !== CAPABILITY_CONTRACT_VERSION)
+        return false;
+    return doc.capabilities.includes(required);
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/platform/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/platform/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAe7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAgC;IAC3D;QACE,GAAG,EAAE,0BAA0B;QAC/B,KAAK,EAAE,wDAAwD;QAC/D,MAAM,EAAE,CAAC,wBAAwB,EAAE,wBAAwB,CAAC;KAC7D;IACD;QACE,GAAG,EAAE,2BAA2B;QAChC,KAAK,EAAE,qBAAqB;QAC5B,MAAM,EAAE,CAAC,yBAAyB,EAAE,yBAAyB,CAAC;KAC/D;IACD;QACE,GAAG,EAAE,2BAA2B;QAChC,KAAK,EAAE,sDAAsD;QAC7D,MAAM,EAAE,CAAC,yBAAyB,EAAE,yBAAyB,CAAC;KAC/D;IACD;QACE,GAAG,EAAE,wBAAwB;QAC7B,KAAK,EAAE,yCAAyC;QAChD,MAAM,EAAE,CAAC,sBAAsB,CAAC;KACjC;IACD;QACE,GAAG,EAAE,6BAA6B;QAClC,KAAK,EAAE,6DAA6D;QACpE,MAAM,EAAE;YACN,2BAA2B;YAC3B,iCAAiC;YACjC,oCAAoC;SACrC;KACF;IACD;QACE,GAAG,EAAE,4BAA4B;QACjC,KAAK,EAAE,2DAA2D;QAClE,MAAM,EAAE;YACN,0BAA0B;YAC1B,8BAA8B;YAC9B,2BAA2B;SAC5B;KACF;IACD;QACE,GAAG,EAAE,6BAA6B;QAClC,KAAK,EACH,yFAAyF;QAC3F,MAAM,EAAE;YACN,6BAA6B;YAC7B,yBAAyB;YACzB,8BAA8B;YAC9B,wBAAwB;YACxB,sBAAsB;YACtB,qCAAqC;YACrC,iCAAiC;SAClC;KACF;IACD;QACE,4EAA4E;QAC5E,yEAAyE;QACzE,yEAAyE;QACzE,4EAA4E;QAC5E,iDAAiD;QACjD,GAAG,EAAE,oCAAoC;QACzC,KAAK,EACH,8FAA8F;QAChG,MAAM,EAAE,CAAC,kCAAkC,CAAC;KAC7C;IACD;QACE,kEAAkE;QAClE,EAAE;QACF,8DAA8D;QAC9D,2EAA2E;QAC3E,yEAAyE;QACzE,sDAAsD;QACtD,GAAG,EAAE,sCAAsC;QAC3C,KAAK,EAAE,uFAAuF;QAC9F,MAAM,EAAE;YACN,sCAAsC;YACtC,iCAAiC;YACjC,qCAAqC;YACrC,mCAAmC;SACpC;KACF;IACD;QACE,uEAAuE;QACvE,yEAAyE;QACzE,sEAAsE;QACtE,mEAAmE;QACnE,GAAG,EAAE,gCAAgC;QACrC,KAAK,EACH,qIAAqI;QACvI,MAAM,EAAE;YACN,uCAAuC;YACvC,uCAAuC;YACvC,kCAAkC;SACnC;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAsB,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAEzF,mFAAmF;AACnF,MAAM,CAAC,MAAM,sBAAsB,GACjC,iEAAiE,CAAC;AAOpE;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAA0C,EAC1C,QAAgB;IAEhB,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,IAAI,GAAG,CAAC,QAAQ,KAAK,2BAA2B;QAAE,OAAO,KAAK,CAAC;IAC/D,OAAO,GAAG,CAAC,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC7C,CAAC"}

package/dist/platform/job-contract.d.ts

@@ -0,0 +1,232 @@
+import type { Db, Tx } from '../db/client.js';
+/**
+ * O contrato de capacidade entre um WORKER e o schema que ele opera.
+ *
+ * ## O que isto fecha, e por que não bastava o contrato HTTP
+ *
+ * `platform/capabilities.ts` protege a superfície HTTP: a tela pergunta à API
+ * se aquele build sabe responder o que ela vai pedir. Um cron não tem tela e
+ * não fala com a API — ele fala com o BANCO. A contraparte é outra, então o
+ * contrato é outro, e o registro vive no próprio banco (migration 0055).
+ *
+ * A janela é real e não é hipótese: os crons publicam na Render como serviços
+ * SEPARADOS do serviço web, e as migrations rodam no `preDeployCommand` do
+ * serviço web. A ordem entre "a imagem nova do cron subiu" e "o schema novo foi
+ * aplicado" não é garantida por nada.
+ *
+ * ## Cinco estados, não dois
+ *
+ * A primeira forma óbvia disto seria um booleano `podeRodar`. Ela colapsa dois
+ * problemas que exigem tratamentos opostos:
+ *
+ *   `READY`                     compatível — executa.
+ *   `INCOMPATIBLE`              o schema é anterior ao que este worker exige.
+ *                               Fecha, e **não** merece retry: nenhuma
+ *                               quantidade de tentativas aplica uma migration.
+ *   `TEMPORARILY_UNAVAILABLE`   não deu para perguntar (banco fora, timeout).
+ *                               Fecha também — mas com backoff, porque volta
+ *                               sozinho.
+ *   `DISABLED`                  desligado por configuração do processo.
+ *   `BLOCKED_BY_TENANT_CONFIG`  o escritório não habilitou.
+ *
+ * A distinção entre os dois primeiros bloqueios é a mesma que o contrato HTTP
+ * já paga: lá, tratar timeout como "não suportado" faria a tela mentir sobre um
+ * deploy antigo toda vez que a API hibernasse. Aqui, tratar banco fora como
+ * incompatível faria o cron desistir de um dia inteiro por uma queda de rede de
+ * trinta segundos — e tratar incompatível como indisponível faria ele martelar
+ * um schema que não vai mudar sozinho.
+ *
+ * ## Fail-closed é sobre VERSÃO
+ *
+ * Quando não é `READY`, nada é escrito: zero mutação, cursor intocado, nenhum
+ * item marcado como processado. E o bloqueio é REGISTRADO (`job_run`) — um job
+ * que para em silêncio é indistinguível de um job que rodou e não achou nada.
+ *
+ * A garantia não depende deste arquivo: `job_run` tem CHECK que torna
+ * ingravável um run bloqueado com mutação ou cursor avançado. O TypeScript
+ * ordena; o banco garante.
+ */
+/** Versão do FORMATO do registro. Ver `platform_capability.contract_version`. */
+export declare const JOB_CONTRACT_VERSION = 1;
+export interface JobDefinition {
+    /** Slug estável do worker. É ele que aparece em `job_run` e `job_cursor`. */
+    readonly name: string;
+    /** Versão do WORKER. Sobe quando o que ele exige ou escreve muda. */
+    readonly version: number;
+    /**
+     * Capacidades que este worker exige do schema.
+     *
+     * Vazio é proibido por desenho — um worker sem exigência tem um portão que
+     * nunca fecha, e um portão que nunca fecha não é portão. Se um job realmente
+     * não depende de schema novo, ele deve exigir a capacidade que descreve o que
+     * ele JÁ usa; foi para isso que a 0055 declarou as dos dois crons existentes.
+     */
+    readonly requires: readonly string[];
+    /** Menor versão de contrato que este worker sabe ler. */
+    readonly minContractVersion: number;
+}
+export type JobReadiness = 'READY' | 'TEMPORARILY_UNAVAILABLE' | 'INCOMPATIBLE' | 'DISABLED' | 'BLOCKED_BY_TENANT_CONFIG';
+export type PlatformCapabilityProbe = {
+    status: 'declared';
+    contract: number;
+    capabilities: readonly string[];
+}
+/** O schema respondeu e não conhece o contrato: é a versão anterior. */
+ | {
+    status: 'absent';
+    detail: string;
+}
+/** Não foi possível perguntar. Diz respeito à infraestrutura, não à versão. */
+ | {
+    status: 'unknown';
+    detail: string;
+};
+export interface JobDecision {
+    readiness: JobReadiness;
+    /** Somente `READY` autoriza mutação. */
+    canMutate: boolean;
+    /** `INCOMPATIBLE` não é retentável: só um deploy o resolve. */
+    retryable: boolean;
+    /** Sugestão de espera para o que volta sozinho. `null` quando não retenta. */
+    backoffMs: number | null;
+    contractVersion: number | null;
+    observed: readonly string[];
+    missing: readonly string[];
+    detail: string;
+}
+/**
+ * Backoff do que volta sozinho.
+ *
+ * Cinco minutos: longo o bastante para uma reinicialização de banco caber
+ * dentro, curto o bastante para o ciclo diário ainda sair no mesmo dia.
+ */
+export declare const TEMPORARY_BACKOFF_MS: number;
+/**
+ * Lê o registro de capacidades do schema. Nunca lança; classifica a falha.
+ *
+ * A classificação é o ponto inteiro da função. Um `catch` que devolvesse
+ * "incompatível" para qualquer erro transformaria toda queda de rede em uma
+ * afirmação falsa sobre a versão do schema — o mesmo defeito que quase entrou
+ * em produção no contrato HTTP.
+ */
+export declare function probePlatformCapabilities(tx: Tx | Db): Promise<PlatformCapabilityProbe>;
+/**
+ * A sondagem satisfaz o que este worker exige?
+ *
+ * Função pura: recebe a sondagem já feita e devolve a decisão. É essa separação
+ * que permite fixar o contrato para o lote inteiro (ver `runGuardedJob`) — a
+ * decisão de cada item usa a MESMA sondagem, não uma nova.
+ */
+export declare function evaluateJobReadiness(def: JobDefinition, probe: PlatformCapabilityProbe, opts?: {
+    disabled?: boolean;
+    tenantBlocked?: string | null;
+}): JobDecision;
+export interface JobRunRecord {
+    id: string;
+    readiness: JobReadiness;
+    status: 'completed' | 'blocked' | 'failed';
+    mutations: number;
+    cursorAdvanced: boolean;
+    detail: string;
+}
+export interface GuardedJobContext {
+    /** A decisão FIXADA para este lote. Não muda no meio. */
+    readonly decision: JobDecision;
+    /** Cursor lido no início. `null` quando o job nunca rodou neste tenant. */
+    readonly cursor: string | null;
+    /** Conte aqui cada escrita. É o número que o CHECK do banco confere. */
+    recordMutation(n?: number): void;
+    /** Peça o avanço do cursor. Só é aplicado se o lote terminar. */
+    advanceCursorTo(position: string): void;
+}
+export interface GuardedJobOptions {
+    /** Desligado pelo processo (variável de ambiente, chave geral). */
+    disabled?: boolean;
+    /** Motivo de bloqueio por configuração do escritório, quando houver. */
+    tenantBlocked?: string | null;
+    /**
+     * Sondagem já feita, para FIXAR o contrato ao longo de um processo que
+     * percorre muitos tenants. Sem isto, o tenant 40 poderia decidir sob um
+     * registro diferente do tenant 1 — e metade do dia rodaria sob cada contrato.
+     */
+    probe?: PlatformCapabilityProbe;
+}
+/**
+ * Executa `handler` sob o portão, dentro do contexto de tenant.
+ *
+ * A ordem importa e é o mecanismo inteiro:
+ *
+ *  1. sonda (ou usa a sondagem fixada) e decide — ANTES de qualquer escrita;
+ *  2. se não for `READY`, grava o `job_run` bloqueado e RETORNA. O handler não
+ *     é chamado, então não existe caminho pelo qual ele mute;
+ *  3. se for `READY`, lê o cursor, chama o handler, e só então grava o run e
+ *     avança o cursor.
+ *
+ * Cursor e run são gravados na MESMA transação do handler: um lote que estourou
+ * no meio não deixa cursor avançado, porque o rollback leva os dois junto.
+ */
+export declare function runGuardedJob<T>(db: Db, tenantId: string, def: JobDefinition, handler: (tx: Tx, ctx: GuardedJobContext) => Promise<T>, opts?: GuardedJobOptions): Promise<{
+    record: JobRunRecord;
+    result: T | null;
+    decision: JobDecision;
+}>;
+/**
+ * Grava o desfecho de um run.
+ *
+ * Público porque os dois crons existentes não são baseados em cursor — eles são
+ * idempotentes por índice único e rodam duas transações por tenant de
+ * propósito. Forçá-los para dentro de `runGuardedJob` colapsaria essas duas
+ * transações em uma, e um erro na régua passaria a desfazer recebíveis
+ * legitimamente gerados. Eles usam o mesmo portão e a mesma trilha; o que não
+ * usam é o cursor, que não têm.
+ */
+export declare function recordJobRun(tx: Tx, tenantId: string, def: JobDefinition, decision: JobDecision, outcome: {
+    status: 'completed' | 'blocked' | 'failed';
+    mutations: number;
+    cursorAdvanced: boolean;
+}): Promise<JobRunRecord>;
+/**
+ * Grava a trilha tolerando a ausência da própria tabela.
+ *
+ * O caso é específico e derrubaria produção: quando o bloqueio é `INCOMPATIBLE`
+ * porque o schema é anterior à 0055, **`job_run` também não existe** — as duas
+ * tabelas nascem na mesma migration. Um `recordJobRun` direto estouraria para
+ * cada tenant e o cron sairia com código 1, transformando um bloqueio correto
+ * e silencioso num alarme de infraestrutura.
+ *
+ * A trilha é observabilidade, não a garantia. A garantia é o handler não ser
+ * chamado, e ela já valeu antes desta linha. Quando a trilha não cabe no
+ * schema, o log carrega o motivo — e ele é o mesmo.
+ *
+ * Devolve `true` se gravou. Só engole falha de SCHEMA (`42P01`/`42703`): erro
+ * de permissão ou de restrição é defeito nosso e tem de subir.
+ */
+export declare function recordJobRunBestEffort(db: Db, tenantId: string, def: JobDefinition, decision: JobDecision, outcome: {
+    status: 'completed' | 'blocked' | 'failed';
+    mutations: number;
+    cursorAdvanced: boolean;
+}): Promise<boolean>;
+/**
+ * Os workers deste produto.
+ *
+ * Declarados aqui, e não junto de cada entrypoint, para que a lista seja
+ * enumerável — é ela que o inventário do gate confere contra o `render.yaml`.
+ */
+export declare const COLLECTION_CYCLE_JOB: JobDefinition;
+export declare const SAAS_BILLING_JOB: JobDefinition;
+/**
+ * O worker fiscal (Onda B · Fase 2).
+ *
+ * Exige DUAS capacidades, e a segunda é o ponto: `office.fiscal-ingestion.v1`
+ * (0056) descreve onde o documento cabe; `office.fiscal-sync-worker.v1` (0058)
+ * descreve o que o worker precisa para OPERAR — lease, política, disjuntor,
+ * fila humana, cobertura.
+ *
+ * Separá-las importa numa janela concreta: um banco que já tem a 0056 e ainda
+ * não tem a 0058 sabe guardar documento e NÃO sabe travar a vez. Um worker que
+ * exigisse só a primeira rodaria ali, sem exclusão mútua, e duas execuções
+ * simultâneas consultariam o mesmo CNPJ contra a Receita.
+ */
+export declare const FISCAL_SYNC_JOB: JobDefinition;
+export declare const KNOWN_JOBS: readonly JobDefinition[];
+//# sourceMappingURL=job-contract.d.ts.map

package/dist/platform/job-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-contract.d.ts","sourceRoot":"","sources":["../../src/platform/job-contract.ts"],"names":[],"mappings":"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"}