@microteia/console 2.10.0 → 2.19.0

package/lib/console/customFunctions.js

@@ -1,6 +1,7 @@
 import { access, cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { callableFunctionNames, declaredParametersIn } from '../kernel/manifest.js';
+import { callableDeclarations, triggerDeclarations, unscopedDeclarations, } from './functionGate.js';
 /**
  * As Cloud Functions do ESCRITÓRIO — as que ele escreve, não as do kernel.
  *
@@ -79,6 +80,33 @@ const readDependencies = async (path, label) => {
     }
     return parsed.dependencies;
 };
+/**
+ * `microteia.serves` do `package.json` do diretório: nome de function -> os ids que ela serve.
+ *
+ * OPCIONAL, como as `dependencies` ao lado. A ausência dela é o comportamento anterior — a function comum
+ * sobe sempre e nunca é retirada —, e o provisionamento diz quais estão nessa situação em vez de calar.
+ */
+const readServes = async (path, label) => {
+    const manifest = join(path, 'package.json');
+    if (!await exists(manifest))
+        return {};
+    const parsed = JSON.parse(await readFile(manifest, 'utf8'));
+    const declared = parsed.microteia?.serves;
+    if (declared === undefined)
+        return {};
+    if (typeof declared !== 'object' || declared === null || Array.isArray(declared)) {
+        throw new Error(`${label}/package.json has a "microteia.serves" that is not an object.`);
+    }
+    const serves = {};
+    for (const [name, ids] of Object.entries(declared)) {
+        if (!Array.isArray(ids) || ids.some((id) => typeof id !== 'string')) {
+            throw new Error(`${label}/package.json declares "microteia.serves.${name}" as something other than a list of `
+                + 'extension ids.');
+        }
+        serves[name] = [...new Set(ids)];
+    }
+    return serves;
+};
 const readSource = async (path, label, slug, shared) => {
     const entry = join(path, 'index.ts');
     if (!await exists(entry)) {
@@ -88,11 +116,19 @@ const readSource = async (path, label, slug, shared) => {
     }
     const exported = exportedNames(await readFile(entry, 'utf8'));
     const callables = new Set();
+    const triggers = [];
+    const unscoped = [];
+    const callableGuards = [];
     const parameters = new Map();
     for (const file of await sourceFiles(path)) {
         const source = await readFile(file, 'utf8');
         for (const name of callableFunctionNames(source))
             callables.add(name);
+        // O gatilho é declarado no arquivo dele e reexportado pelo `index.ts` — é o que o molde escreve —,
+        // então a varredura é a mesma das callables: todo `.ts`, e o `index.ts` decide o que conta.
+        triggers.push(...triggerDeclarations(source));
+        unscoped.push(...unscopedDeclarations(source));
+        callableGuards.push(...callableDeclarations(source));
         // Um nome declarado em vários lugares é UM parâmetro, e ele é exigido se ALGUMA declaração o pede
         // sem `default`: é essa que recusa o deploy quando o valor falta, e a conservadora é a que avisa.
         for (const parameter of declaredParametersIn(source)) {
@@ -112,8 +148,12 @@ const readSource = async (path, label, slug, shared) => {
         // Só as que o `index.ts` de fato exporta: uma callable escrita e não exportada não é deployada, e
         // conferir o alcance dela mandaria procurar um erro que não existe.
         callables: exported.filter((name) => callables.has(name)),
+        triggers,
+        unscoped,
+        callableGuards,
         parameters: [...parameters.values()].sort((a, b) => a.name.localeCompare(b.name)),
         dependencies: await readDependencies(path, label),
+        serves: await readServes(path, label),
     };
 };
 /** Onde o escritório pode ter escrito function, na ordem em que as mensagens as citam. */
@@ -146,10 +186,21 @@ export const officeFunctionsOf = (sources) => {
             });
         }
     }
+    const shared = sources.filter((source) => source.shared);
+    const declared = new Map();
+    for (const source of shared) {
+        for (const [name, ids] of Object.entries(source.serves))
+            declared.set(name, ids);
+    }
+    const sharedNames = shared.flatMap((source) => source.exported);
     return {
         sources,
         all: sources.flatMap((source) => source.exported),
-        shared: sources.filter((source) => source.shared).flatMap((source) => source.exported),
+        shared: sharedNames,
+        served: sharedNames
+            .filter((name) => declared.has(name))
+            .map((name) => ({ name, serves: declared.get(name) ?? [] })),
+        unserved: sharedNames.filter((name) => !declared.has(name)),
         callables: sources.flatMap((source) => source.callables),
         parameters: [...parameters.values()].sort((a, b) => a.name.localeCompare(b.name)),
     };
@@ -165,6 +216,41 @@ export const readOfficeFunctions = async (root) => officeFunctionsOf(await findF
  * silêncio — e substituir um gatilho do kernel é o tipo de defeito que só aparece quando algo deixa de
  * acontecer, sem erro em lugar nenhum.
  */
+/**
+ * O que impede `microteia.serves` de ser levado a sério.
+ *
+ * As três recusas têm o mesmo motivo: a declaração é o que autoriza a plataforma a RETIRAR a function
+ * comum, e uma declaração que não fecha faria a retirada acontecer pelo motivo errado — ou não acontecer,
+ * e nada diria por quê.
+ */
+export const servesProblems = (sources) => {
+    const problems = [];
+    for (const source of sources) {
+        const declared = Object.entries(source.serves);
+        if (declared.length === 0)
+            continue;
+        // A function de extensão já tem dono, e ele vem do LUGAR do arquivo. Declarar de novo, e num lugar
+        // que só a comum consulta, criaria duas autoridades sobre a mesma retirada.
+        if (!source.shared) {
+            problems.push(`${source.label}/package.json declares "microteia.serves", which only ${FUNCTIONS_DIR}/ uses — a `
+                + "function of an extension is already owned by the folder it is in, and is declared in that "
+                + 'extension\'s manifest.backend.functions');
+            continue;
+        }
+        const exported = new Set(source.exported);
+        for (const [name, ids] of declared) {
+            if (!exported.has(name)) {
+                problems.push(`${source.label}/package.json says "${name}" serves ${ids.join(', ') || 'nothing'}, but `
+                    + `${source.label}/index.ts does not export it`);
+            }
+            if (ids.length === 0) {
+                problems.push(`${source.label}/package.json declares "${name}" as serving no extension at all — name the `
+                    + 'extensions it exists for, or leave it out of microteia.serves');
+            }
+        }
+    }
+    return problems;
+};
 export const functionProblems = (sources, kernelFunctions) => {
     const problems = [];
     const kernel = new Set(kernelFunctions);
@@ -186,6 +272,12 @@ export const functionProblems = (sources, kernelFunctions) => {
             }
         }
     }
+    problems.push(...servesProblems(sources));
+    // O portão de instalação NÃO entra aqui. Esta porta responde "dá para montar o conjunto?", e a
+    // resposta dela vale para toda fonte que existe no disco — inclusive a da extensão que foi
+    // desinstalada e cujo diretório ficou. O portão responde outra coisa: "esta function pode ir para o
+    // ar?", e ela só é devida de quem vai. Quem pergunta é `gateProblemsFor`, no ponto em que os nomes
+    // que sobem já estão decididos: `deploy` contra a baseline mais as comuns, `provision` contra a fila.
     return problems;
 };
 const barrel = (sources) => `// Generated by "microteia deploy". Do not edit.

package/lib/console/deploy.js

@@ -7,6 +7,7 @@ import { ENVIRONMENT_FILE, readEnvironment, writeEnvironment } from './environme
 import { FIREBASE_BIN } from './firebaseCli.js';
 import { reportFailures, reportNotices } from './deployFunctions.js';
 import { clearRegionOrphans, listDeployedFunctions } from './regionOrphans.js';
+import { gateProblemsFor } from './functionGate.js';
 import { deployFunctionsThatChanged } from './functionsUpToDate.js';
 import { checkCallables, invokerGrantCommand } from './callableAccess.js';
 import { checkHostingServed, htmlIsRevalidated } from './hostingCheck.js';
@@ -125,17 +126,40 @@ export const deploy = async (args) => {
             // comuns) e `extensions/<plugin>/functions/` (as de cada extensão). O `predeploy` do pacote compila
             // só o `custom/`, então o que não estiver aqui não sobe.
             const gathered = await gatherCustomFunctions(root, install, manifest.functions);
-            // O que sobe aqui é a baseline MAIS as functions comuns do escritório (`functions/`). As de
-            // `extensions/<plugin>/functions/` têm dono e sobem pelo provisionamento, no fim deste comando:
-            // é o mesmo "empacotar não é deployar" que vale para as do kernel reivindicadas por extensão.
-            const own = [...baseline, ...gathered.shared];
+            /**
+             * O que sobe aqui é a baseline MAIS as functions comuns que NÃO dizem a quem servem.
+             *
+             * As de `extensions/<plugin>/functions/` têm dono e sobem pelo provisionamento, no fim deste
+             * comando — é o mesmo "empacotar não é deployar" que vale para as do kernel reivindicadas por
+             * extensão. E a comum que DECLARA quem serve passou a ter a mesma condição, pela mesma razão: ela
+             * é devida enquanto alguma das extensões servidas estiver instalada, e subi-la aqui de qualquer
+             * forma faria o `--prune` apagá-la e este passo repô-la, indefinidamente.
+             *
+             * A comum sem declaração continua subindo sempre. É o comportamento anterior, e mantê-lo é o que
+             * impede esta versão de tirar do ar function de uma instalação que já existe.
+             */
+            const own = [...baseline, ...gathered.unserved];
+            /**
+             * O portão de instalação, cobrado do que ESTE passo sobe — e não de toda fonte que existe no
+             * disco.
+             *
+             * Na prática ele quase nunca tem o que dizer aqui, e isso é a confirmação de que o lugar é este:
+             * o que sobe no `deploy` é a baseline (do kernel) e a comum sem declaração (de quem não há id a
+             * cobrar). É no `provision` que a function de extensão entra na fila, e é lá que a recusa morde.
+             * Cobrar aqui mantém a regra atada ao ato — se um dia esta lista crescer, ela vem coberta.
+             */
+            const refused = gateProblemsFor(gathered.sources, own);
+            if (refused.length > 0) {
+                throw new Error(`These Cloud Functions cannot go up as they are:\n${refused.map((line) => `  ${line}`).join('\n')}`);
+            }
             step(current, total, `Cloud Functions (${own.length}, one at a time)`);
             if (gathered.sources.length > 0) {
                 success(`${gathered.functions.length} function(s) of your own, from `
                     + `${gathered.sources.map((source) => `${source.label}/`).join(', ')}`);
-                const owned = gathered.all.length - gathered.shared.length;
-                if (owned > 0)
-                    info(`  ${owned} of them belong to an extension and go up with "provision"`);
+                const provisioned = gathered.all.length - gathered.unserved.length;
+                if (provisioned > 0) {
+                    info(`  ${provisioned} of them go up with "provision", only where they are needed`);
+                }
             }
             if (Object.keys(gathered.dependencies.added).length > 0) {
                 success(`${Object.keys(gathered.dependencies.added).length} npm dependency(ies) your functions declare: `

package/lib/console/environment.d.ts

@@ -29,13 +29,14 @@ export interface Environment {
         deployed: string | null;
     };
     /**
-     * Quais Cloud Functions de EXTENSÃO já foram deployadas neste projeto. Fica aqui, e não no banco,
-     * porque é estado da instalação e não do escritório — e é o que permite ao `provision` deployar só o
-     * delta e reconhecer o que ficou órfão depois de uma desinstalação.
+     * Quais Cloud Functions de EXTENSÃO já foram deployadas neste projeto, e de QUEM. Fica aqui, e não no
+     * banco, porque é estado da instalação e não do escritório — e é o que permite ao `provision`
+     * deployar só o delta e reconhecer o que ficou órfão depois de uma desinstalação.
      *
-     * Uma lista num escalar separado por vírgula porque o leitor de YAML daqui entende mapas de dois
-     * níveis e escalares, e trazer sequências para guardar meia dúzia de nomes seria pagar caro pela
-     * generalidade.
+     * `nome@pluginId` separado por vírgula — ver `appliedFunctions.ts`, que o lê e o escreve. O escalar é
+     * porque o leitor de YAML daqui entende mapas de dois níveis e escalares, e trazer sequências para
+     * guardar meia dúzia de pares seria pagar caro pela generalidade. Uma entrada sem `@` é o que uma
+     * instalação anterior ao dono gravou, e continua valendo.
      */
     backend: {
         functions: string | null;

package/lib/console/firestoreRest.d.ts

@@ -20,8 +20,26 @@ export type FirestoreTypedValue = {
     stringValue: string;
 } | {
     timestampValue: string;
+} | {
+    integerValue: string;
+} | {
+    arrayValue: {
+        values: FirestoreTypedValue[];
+    };
+} | {
+    mapValue: {
+        fields: Record<string, FirestoreTypedValue>;
+    };
 };
 export declare const asString: (value: string) => FirestoreTypedValue;
+/**
+ * Inteiro como INTEIRO. A REST o transporta em string — é assim que ela representa um int64 sem perder
+ * precisão em JSON —, mas o campo gravado é numérico, e é isso que faz o outro lado do produto poder
+ * compará-lo em vez de tentar convertê-lo.
+ */
+export declare const asInteger: (value: number) => FirestoreTypedValue;
+export declare const asArray: (values: FirestoreTypedValue[]) => FirestoreTypedValue;
+export declare const asMap: (fields: Record<string, FirestoreTypedValue>) => FirestoreTypedValue;
 /**
  * Data como DATA, e não como texto que se parece com uma.
  *
@@ -37,3 +55,12 @@ export declare const asTimestamp: (value: Date) => FirestoreTypedValue;
  * Console carimbar o estado sem conhecer (nem arriscar reescrever) o pacote inteiro que vive ao lado.
  */
 export declare const patchMapField: (projectId: string, path: string, field: string, entries: Record<string, FirestoreTypedValue>) => Promise<void>;
+/**
+ * Grava um documento inteiro, com `updateMask` listando cada campo escrito.
+ *
+ * A máscara é explícita e não omitida de propósito: sem ela o comportamento de um PATCH depende de o
+ * documento existir, e o que se quer aqui é convergência — o que é escrito passa a valer, e nada de uma
+ * execução anterior sobra. Como todos os campos são escritos a cada vez, a máscara completa é também o
+ * que apaga o que deixou de ser verdade.
+ */
+export declare const patchFields: (projectId: string, path: string, fields: Record<string, FirestoreTypedValue>) => Promise<void>;

package/lib/console/firestoreRest.js

@@ -108,6 +108,14 @@ export const listDocuments = async (projectId, path) => {
 };
 export const documentId = (document) => document.name.slice(document.name.lastIndexOf('/') + 1);
 export const asString = (value) => ({ stringValue: value });
+/**
+ * Inteiro como INTEIRO. A REST o transporta em string — é assim que ela representa um int64 sem perder
+ * precisão em JSON —, mas o campo gravado é numérico, e é isso que faz o outro lado do produto poder
+ * compará-lo em vez de tentar convertê-lo.
+ */
+export const asInteger = (value) => ({ integerValue: String(value) });
+export const asArray = (values) => ({ arrayValue: { values } });
+export const asMap = (fields) => ({ mapValue: { fields } });
 /**
  * Data como DATA, e não como texto que se parece com uma.
  *
@@ -129,3 +137,18 @@ export const patchMapField = async (projectId, path, field, entries) => {
         body: { fields: { [field]: { mapValue: { fields: entries } } } },
     });
 };
+/**
+ * Grava um documento inteiro, com `updateMask` listando cada campo escrito.
+ *
+ * A máscara é explícita e não omitida de propósito: sem ela o comportamento de um PATCH depende de o
+ * documento existir, e o que se quer aqui é convergência — o que é escrito passa a valer, e nada de uma
+ * execução anterior sobra. Como todos os campos são escritos a cada vez, a máscara completa é também o
+ * que apaga o que deixou de ser verdade.
+ */
+export const patchFields = async (projectId, path, fields) => {
+    await request(projectId, path, {
+        method: 'PATCH',
+        query: { 'updateMask.fieldPaths': Object.keys(fields) },
+        body: { fields },
+    });
+};

package/lib/console/functionGate.d.ts

@@ -0,0 +1,228 @@
+/**
+ * O portão de instalação, conferido na FONTE.
+ *
+ * `forInstalledExtension` é a metade da retirada que age no instante certo: a Cloud Function é do
+ * PROJETO e a instalação da extensão é do ESCRITÓRIO, então um `onDocumentWritten('tenants/{tenantId}/…')`
+ * declarado por uma extensão dispara para TODOS os escritórios do projeto — os que nunca a instalaram, e
+ * o que a desinstalou enquanto outro a mantém. Nesse último caso `--prune` não pode ajudar: a function
+ * tem de continuar no ar, porque alguém ainda precisa dela.
+ *
+ * Só que nada cobrava o portão. O `create function` o escrevia no molde, e era só isso: nenhuma
+ * verificação do empacotamento, do deploy ou do provisionamento olhava a fonte. Um gatilho sem portão
+ * passava por tudo e ia para o ar — e o sintoma dele é o pior que existe, porque não é uma falha: é
+ * código de uma extensão que ninguém tem mais rodando sobre os dados de quem nunca a pediu, sem erro em
+ * lugar nenhum.
+ *
+ * É recusa, e não aviso, pelo mesmo motivo do nome de function repetido: o defeito é invisível depois de
+ * instalado, e um aviso na saída de um deploy é lido uma vez. Mas ela é cobrada da function que VAI
+ * SUBIR, e não de toda fonte que existe no disco — ver `gateProblemsFor`. Toda origem é lida, sempre, e
+ * o que não vai subir é relatado pelo `provision`: quem tem a fonte parada ao lado do `microteia.yaml`
+ * fica sabendo dela, sem ter o comando trancado por ela.
+ *
+ * A análise é por texto, no idioma dos outros leitores de fonte do Console (`callableFunctionNames`,
+ * `declaredParametersIn`). Ela erra para o lado ALTO — o que ela não entende ela recusa —, e é por isso
+ * que o portão declarado num identificador ao lado é reconhecido: recusar código correto é o que ensina
+ * a desligar a verificação.
+ */
+/**
+ * Os construtores de gatilho de Firestore.
+ *
+ * São os únicos eventos cujo caminho carrega `{tenantId}`, e portanto os únicos para os quais o portão
+ * existe. Um `onSchedule` ou um `onMessagePublished` não tem escritório de onde perguntar — envolvê-los
+ * no portão os deixaria permanentemente inertes, porque ele falha FECHADO. Eles ficam de fora desta
+ * verificação de propósito: exigir deles um portão que não funciona seria trocar um defeito por outro.
+ */
+export declare const TENANT_TRIGGER_CONSTRUCTORS: string[];
+/**
+ * Os construtores cujo evento NÃO carrega escritório no caminho.
+ *
+ * Para eles as duas saídas do autor eram erradas, e é isso que faz deles uma recusa e não um aviso: sem
+ * portão a function age sobre o projeto inteiro; COM portão ela nunca roda — nem enquanto a extensão está
+ * instalada —, porque `forInstalledExtension` falha FECHADO e nunca acha o `{tenantId}` que não existe.
+ * Um autor que seguisse a orientação genérica "envolva o handler no portão" produzia uma function que
+ * passava no deploy, não acusava nada e nunca fazia nada.
+ *
+ * A resposta é o laço por escritório (`forEachInstalledOffice`), e é por existir uma resposta que a
+ * recusa é honesta.
+ *
+ * A lista é EXPLÍCITA, e não "tudo o que não é gatilho de documento": o que não se conhece não se recusa.
+ * O RTDB fica de fora de propósito — o caminho dele TEM parâmetros, então um `{tenantId}` ali é possível
+ * —, e a plataforma não usa RTDB em lugar nenhum.
+ */
+export declare const UNSCOPED_TRIGGER_CONSTRUCTORS: string[];
+/**
+ * A fonte sem comentário nenhum, com as strings intactas.
+ *
+ * O JSDoc que o molde escreve CITA `forInstalledExtension` — é ali que ele explica o portão. Sem esta
+ * limpeza, um gatilho que perdesse a chamada e mantivesse o comentário passaria na verificação, o que é
+ * o caso exato que ela existe para pegar.
+ */
+export declare const withoutComments: (source: string) => string;
+export interface TriggerDeclaration {
+    /** O nome declarado — é por ele que se sabe se o `index.ts` o exporta. */
+    name: string;
+    /** O construtor usado. Aparece na mensagem: é ele que explica por que o portão é devido. */
+    trigger: string;
+    /** O id que `forInstalledExtension` recebeu, ou `null` quando o portão não está lá. */
+    gatedFor: string | null;
+    /** Todos os ids que as guardas daquele gatilho recebem — a comum guarda mais de um. */
+    guards: string[];
+}
+/** Os gatilhos de Firestore declarados numa fonte, com o estado do portão de cada um. */
+export declare const triggerDeclarations: (rawSource: string) => TriggerDeclaration[];
+/**
+ * As functions sem escritório no evento, e o id que o laço por escritório recebeu no ARQUIVO.
+ *
+ * O alcance é o arquivo, e não os parênteses da chamada — a diferença é deliberada. O portão de um
+ * gatilho de documento embrulha AQUELE handler, então ele tem de estar ali; o laço, ao contrário, roda
+ * DENTRO do handler e pode estar algumas chamadas abaixo, num `syncOffice(tenantId)` que o próprio autor
+ * escreveu. Exigi-lo nos parênteses recusaria código correto, e a verificação que erra assim é a que
+ * ensina a próxima pessoa a desligá-la.
+ *
+ * O preço é conhecido: dois agendados no mesmo arquivo, um com laço e outro sem, passam os dois. É menos
+ * grave que o inverso, e está dito.
+ */
+export declare const unscopedDeclarations: (rawSource: string) => TriggerDeclaration[];
+/**
+ * As callables declaradas, e o id que a guarda delas recebeu no ARQUIVO.
+ *
+ * O alcance é o arquivo pela mesma razão do laço por escritório: a guarda roda DENTRO do handler (ela
+ * precisa do `request`), e o guia manda o autor manter o handler fino, com a decisão num arquivo ao
+ * lado. Exigi-la nos parênteses recusaria justamente o código que o guia pede.
+ */
+export declare const callableDeclarations: (rawSource: string) => TriggerDeclaration[];
+/**
+ * O que uma origem de functions precisa ter para ser conferida. É a forma de `FunctionSource`, declarada
+ * aqui em vez de importada: assim este módulo se testa sozinho, sem montar diretório nenhum.
+ */
+export interface GateSubject {
+    label: string;
+    /** `functions/` é comum a várias extensões, e não tem uma instalação de onde perguntar. */
+    shared: boolean;
+    exported: string[];
+    triggers: TriggerDeclaration[];
+    /** As functions cujo evento não carrega escritório: o agendado, a fila, o HTTP, o Storage. */
+    unscoped: TriggerDeclaration[];
+    /** Quem cada function comum declara servir. Vazio numa origem de extensão. */
+    serves: Record<string, string[]>;
+    /** As callables declaradas, com o estado da guarda de cada uma. */
+    callableGuards: TriggerDeclaration[];
+}
+/**
+ * Um problema de portão, e a function a que ele pertence.
+ *
+ * O nome está aqui porque é ele que decide o PESO do problema. A verificação lê toda fonte que existe no
+ * disco — é assim que ela acha o que precisa achar —, mas o que existe no disco não é o que vai subir:
+ * `extensions/<x>/functions/` de uma extensão que ninguém instalou é lida, copiada e nunca deployada.
+ * Sem o nome, quem chama só tem a frase, e a única coisa que dá para fazer com uma frase é recusar tudo.
+ * Foi o que acontecia: uma extensão desinstalada, com a fonte parada ao lado do `microteia.yaml`,
+ * trancava o `deploy` inteiro — hosting, rules e índices junto — por causa de uma function que nenhum
+ * comando teria subido.
+ */
+export interface GateProblem {
+    /** A function a que o problema pertence. É por ela que se sabe se ela vai, de fato, subir. */
+    name: string;
+    message: string;
+}
+/**
+ * Gatilho de extensão sem portão.
+ *
+ * `functions/` fica de fora porque ali a pergunta não tem resposta: a function é comum a várias
+ * extensões, nenhuma a reivindica, e não há um id para o portão receber. É lacuna conhecida e tem
+ * endereço próprio — enquanto ela não fechar, exigir aqui um portão impossível seria recusar a única
+ * forma que a plataforma oferece para uma function compartilhada.
+ */
+export declare const ungatedTriggerProblems: (subjects: GateSubject[]) => GateProblem[];
+/**
+ * Function de extensão cujo evento não tem escritório, e que não passa pelo laço.
+ *
+ * A recusa vem acompanhada do substituto porque sem ele ela seria só uma porta fechada: o laço por
+ * escritório (`forEachInstalledOffice`) existe justamente para este caso, e é ele que a mensagem nomeia.
+ *
+ * `functions/` fica de fora pelo mesmo motivo de sempre: a comum não tem um id de extensão para dar ao
+ * laço. Quem responde por ela é a declaração de quem ela serve.
+ */
+export declare const unscopedTriggerProblems: (subjects: GateSubject[]) => GateProblem[];
+/**
+ * Gatilho de uma function COMUM que declara quem serve, e não guarda ninguém.
+ *
+ * A comum ficava fora desta cobrança porque não havia id para dar à guarda: nenhuma extensão pode
+ * reivindicá-la. `microteia.serves` resolve exatamente isso — a partir dela existem ids, e a partir dos
+ * ids a cobrança passa a ser possível. Um gatilho comum sem guarda dispara para todo escritório do
+ * projeto, e é o mesmo defeito do gatilho de extensão sem portão, com um alcance maior.
+ *
+ * A comum SEM declaração continua de fora, e é deliberado: cobrar dela uma guarda sem ter ids a oferecer
+ * seria fechar a porta sem abrir nenhuma. O que ela recebe é o relato do provisionamento.
+ *
+ * A segunda recusa é a guarda que nomeia extensão que a function não declara servir: as duas listas
+ * respondem à mesma pergunta em dois lugares, e divergirem faz uma delas mentir — a `serves` decide a
+ * retirada, a guarda decide a execução, e a function passaria a agir onde não pode ser retirada.
+ */
+export declare const unguardedSharedProblems: (subjects: GateSubject[]) => GateProblem[];
+/**
+ * Callable de extensão sem a guarda de instalação.
+ *
+ * "Uma callable órfã é inerte" era verdade de INTERFACE, e não de segurança — e era a frase que o guia
+ * dizia. O deploy concede a `allUsers` o papel `roles/run.invoker` em cada callable; o que sobra depois é
+ * a validação do token do Firebase. Então a tela ir embora com a extensão não fecha nada: o endpoint
+ * segue no ar aceitando o token de QUALQUER usuário do projeto, de qualquer escritório, tendo ou não a
+ * extensão.
+ *
+ * E o escritório chega no PAYLOAD, porque `useCallable` manda só o que a tela passou. Sem a guarda, um
+ * usuário do escritório A chama a function apontando para o B — e o molde gerado conferia apenas se
+ * havia `request.auth`.
+ *
+ * A comum fica de fora: `requireInstalledExtension` pede UM id, e a comum serve vários. É lacuna
+ * conhecida e está registrada — a guarda "alguma das que eu sirvo" existe para gatilho, não para
+ * callable.
+ */
+export declare const unguardedCallableProblems: (subjects: GateSubject[]) => GateProblem[];
+/** Todo problema de portão de um conjunto de origens, na ordem em que as mensagens os citam. */
+export declare const gateProblems: (subjects: GateSubject[]) => GateProblem[];
+/**
+ * Os problemas das functions que ESTÃO subindo — a lista que autoriza uma recusa.
+ *
+ * É a diferença entre "a fonte foi lida" e "a function vai para o ar", e ela não é sutil: a primeira
+ * inclui toda extensão cujo diretório ficou no disco depois de desinstalada, e recusar por causa dela é
+ * recusar um comando que não faria nada de errado. A segunda é o momento em que a recusa tem
+ * consequência — e é o único em que ela é devida.
+ */
+export declare const gateProblemsFor: (subjects: GateSubject[], deploying: string[]) => string[];
+export interface MisgatedTrigger {
+    /** A origem, como as mensagens a citam. */
+    label: string;
+    name: string;
+    /** O id que a guarda recebeu. */
+    gatedFor: string;
+    /** O id da extensão que reivindica a function. */
+    owner: string;
+    /** Qual guarda recebeu o id errado — é ela que o autor tem de corrigir. */
+    via: string;
+}
+/**
+ * Portão aberto para o id ERRADO.
+ *
+ * É o defeito do copiar-e-colar entre extensões, e o sintoma dele é o oposto do gatilho sem portão: a
+ * function sobe, o gatilho dispara, e o handler nunca roda em escritório nenhum. Nada falha — a extensão
+ * apenas não faz o que promete, e a causa está numa string.
+ *
+ * Devolve os casos, e não as frases, porque quem chama precisa dos dois: a mensagem para relatar e o id
+ * da extensão para pendurar. Deduzir o id de volta a partir do texto é o que faz um relatório recusar a
+ * extensão errada quando o nome de uma aparece dentro da mensagem de outra.
+ *
+ * Só se pergunta quando o nome tem UM reivindicante: com dois, `functionClaimProblems` já recusou antes,
+ * e apontar um deles como o dono certo seria inventar uma resposta.
+ */
+export declare const misgatedTriggers: (subjects: GateSubject[], claimants: Map<string, string>) => MisgatedTrigger[];
+/** Como uma guarda de id errado aparece num relatório. */
+export declare const describeMisgated: (entry: MisgatedTrigger) => string;
+/**
+ * Quem reivindica cada nome, quando é um só. Duas extensões pedindo o mesmo nome é problema de outra
+ * verificação, e o nome sai daqui em vez de receber um dono escolhido a esmo.
+ */
+export declare const singleClaimants: (claims: {
+    pluginId: string;
+    backend: {
+        functions?: string[];
+    };
+}[]) => Map<string, string>;