@microteia/console 2.10.0 → 2.19.0

package/lib/console/provision.js

@@ -2,7 +2,7 @@ import { dirname, join, resolve } from 'node:path';
 import { hasFlag, requiredFlag, flagValue } from '../shared/args.js';
 import { run } from '../shared/run.js';
 import { blank, bullets, failure, heading, info, step, success, warn } from '../shared/ui.js';
-import { backendFingerprint, claimedIndexes, claimedParameters, functionClaimProblems, hasBackendRequirement, indexKey, } from '../kernel/backendShape.js';
+import { backendFingerprint, baselineClaimProblems, claimedIndexes, claimedParameters, functionClaimProblems, hasBackendRequirement, indexKey, sharedClaimProblems, } from '../kernel/backendShape.js';
 import { convergeIndexes, describeIndex, parseIndexState, readIndexFile, serializeIndexState, writeIndexFile, } from './backendIndexes.js';
 import { officeEnvPath, stageOfficeEnv } from './backendEnv.js';
 import { installPath, readInstalledManifest } from './unpack.js';
@@ -14,8 +14,11 @@ import { clearRegionOrphans, listDeployedFunctions } from './regionOrphans.js';
 import { outdatedByStamp } from './functionsUpToDate.js';
 import { checkCallables, invokerGrantCommand } from './callableAccess.js';
 import { asString, asTimestamp, patchMapField } from './firestoreRest.js';
+import { writeBackendResidue } from './backendResidue.js';
 import { listTenants, readInstalledExtensions } from './installedExtensions.js';
 import { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js';
+import { describeMisgated, gateProblems, misgatedTriggers, singleClaimants, } from './functionGate.js';
+import { appliedAfterRun, classifyApplied, describeApplied, parseAppliedFunctions, serializeAppliedFunctions, straysInProject, } from './appliedFunctions.js';
 /**
  * O que cada escritório do projeto instalou e exige do backend.
  *
@@ -23,13 +26,17 @@ import { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js
  * contra `manifest.functions` antes de qualquer deploy. Nome de function fora do pacote é recusado com
  * explicação; não há injeção possível, porque o código é sempre o do pacote.
  */
-export const readInstalledClaims = async (projectId) => {
+export const surveyInstallations = async (projectId) => {
     const tenants = await listTenants(projectId);
     const claims = [];
+    const installedIds = new Set();
+    let extensions = 0;
     for (const tenant of tenants) {
         for (const extension of await readInstalledExtensions(projectId, tenant.id)) {
+            extensions += 1;
             if (!extension.active)
                 continue;
+            installedIds.add(extension.id);
             const backend = extension.manifest?.backend;
             if (!hasBackendRequirement(backend))
                 continue;
@@ -45,7 +52,12 @@ export const readInstalledClaims = async (projectId) => {
             });
         }
     }
-    return claims.sort((a, b) => (a.pluginId < b.pluginId ? -1 : a.pluginId > b.pluginId ? 1 : 0));
+    return {
+        tenants: tenants.length,
+        extensions,
+        claims: claims.sort((a, b) => (a.pluginId < b.pluginId ? -1 : a.pluginId > b.pluginId ? 1 : 0)),
+        installedIds,
+    };
 };
 const uniqueByPlugin = (claims) => {
     const seen = new Set();
@@ -56,7 +68,6 @@ const uniqueByPlugin = (claims) => {
         return true;
     });
 };
-export const parseAppliedFunctions = (value) => (value ?? '').split(',').map((name) => name.trim()).filter((name) => name !== '');
 /**
  * O motor: alinha o projeto Firebase com o que as extensões instaladas exigem, e carimba nelas o
  * estado. Um motor só, chamado pelo `deploy` no fim e pelo `provision` sozinho — duas implementações
@@ -77,12 +88,26 @@ export const provisionBackend = async (options) => {
      */
     const office = await readOfficeFunctions(root);
     const deployable = [...manifest.functions, ...office.all];
-    const claims = await readInstalledClaims(projectId);
-    const problems = functionClaimProblems(claims, deployable);
+    const survey = await surveyInstallations(projectId);
+    const claims = survey.claims;
+    const missing = functionClaimProblems(claims, deployable);
+    const overlapping = baselineClaimProblems(claims, manifest.baselineFunctions ?? []);
+    // A comum do escritório tem o MESMO desfecho da function da plataforma, e por isso a mesma recusa: o
+    // `deploy` a sobe sempre, então reivindicá-la não muda nada — até o dia em que `--prune` a apaga.
+    const appropriated = sharedClaimProblems(claims, office.shared);
+    // O portão aberto para o id de OUTRA extensão. Só aqui se pode perguntar: é a reivindicação que diz de
+    // quem a function é, e ela vem do banco do escritório — o `deploy` não a tem.
+    const misgated = misgatedTriggers(office.sources, singleClaimants(claims));
+    const problems = [
+        ...missing,
+        ...overlapping,
+        ...appropriated,
+        ...misgated.map(describeMisgated),
+    ];
     const rejected = new Set();
-    if (problems.length > 0) {
+    if (missing.length > 0) {
         warn('some extensions ask for backend artifacts that are nowhere to be found:');
-        bullets(problems);
+        bullets(missing);
         // A mensagem sozinha é um beco sem saída: ela diz que o nome não existe, e não onde ele deveria
         // existir. As duas respostas possíveis são estas, e a segunda é a que mais acontece — a function é
         // da extensão, o autor a declarou, e ninguém a exportou do `index.ts` do diretório dela.
@@ -93,18 +118,96 @@ export const provisionBackend = async (options) => {
         ]);
         info(`  this installation currently exports ${office.all.length} function(s) of its own`
             + `${office.all.length === 0 ? '' : `: ${office.all.join(', ')}`}`);
+    }
+    if (overlapping.length > 0) {
+        warn('some extensions claim a function that belongs to the platform itself:');
+        bullets(overlapping);
+        info('  every "microteia deploy" puts those up, extension or no extension, so claiming one changes');
+        info('  nothing while it is installed — and takes a working trigger out of this project the day it');
+        info('  is uninstalled. Rename the extension\'s own function, or drop the name from its');
+        info('  manifest.backend.functions.');
+    }
+    if (appropriated.length > 0) {
+        warn('some extensions claim a function that is shared by this whole installation:');
+        bullets(appropriated);
+        info('  functions/ next to microteia.yaml is the place for a function that serves SEVERAL');
+        info('  extensions, so it has no owner and every "microteia deploy" puts it up. Claiming one changes');
+        info('  nothing while the extension is installed — and the day it is uninstalled the function turns');
+        info('  into an orphan, --prune deletes it, and the next deploy puts it back. Whoever else depended');
+        info('  on it loses their backend in a window nothing explains. Move the function into');
+        info('  extensions/<folder>/functions/ if it is really this extension\'s, drop the name from its');
+        info('  manifest.backend.functions, or — if several extensions need it — name them in "microteia" ->');
+        info('  "serves" in functions/package.json, which is how a shared function gets withdrawn.');
+    }
+    /**
+     * O portão é RELATADO por inteiro aqui, e COBRADO uma a uma na fila de deploy, mais abaixo.
+     *
+     * A assimetria é deliberada, e é o que este comando exige: ele é o único capaz de RETIRAR uma function
+     * do projeto. Recusar o comando inteiro trancaria `--prune` — que é justamente quem apaga a órfã — por
+     * causa de uma fonte que a órfã não tem nada a ver. Então a fonte defeituosa sai da fila, é dita em voz
+     * alta, o comando termina em erro por causa dela, e tudo o mais acontece.
+     *
+     * O relato é de TODAS, e não só das que estão subindo agora: uma fonte com portão faltando é uma
+     * function que ninguém vai conseguir deployar, e descobrir isso no dia da instalação da extensão é
+     * tarde. Aqui o que ela custa é uma linha.
+     */
+    const gateFaults = gateProblems(office.sources);
+    const gateFaultBy = new Map(gateFaults.map((fault) => [fault.name, fault.message]));
+    if (gateFaults.length > 0) {
+        warn(`${gateFaults.length} function(s) written in this installation act outside any office's`
+            + ' installation:');
+        bullets(gateFaults.map((fault) => fault.message));
+        info('  each one is refused the moment this command tries to deploy IT — the others go up as');
+        info('  usual, and a source sitting here for an extension nobody installed blocks nothing.');
+        info('  Whatever is already in the air keeps acting on every office in this project.');
+    }
+    /**
+     * A comum SEM declaração de quem serve. Ela continua subindo no `deploy`, sempre, e nada a retira — é
+     * o comportamento anterior, mantido para não quebrar instalação nenhuma.
+     *
+     * O que muda é que ele deixa de ser invisível. Era esse o defeito: quem herdasse a instalação não tinha
+     * como saber que aquelas functions estavam fora do mecanismo de retirada, e a única forma de descobrir
+     * era um gatilho disparando anos depois de a última extensão que o usava ter saído.
+     */
+    if (office.unserved.length > 0) {
+        blank();
+        info(`  ${office.unserved.length} shared function(s) do not say which extensions they serve:`);
+        bullets(office.unserved);
+        info('  they go up with every "microteia deploy" and nothing here withdraws them — not even --prune.');
+        info('  Name the extensions each one exists for in "microteia" -> "serves" in functions/package.json,');
+        info('  and they are deployed only while one of those is installed, and removed when none is.');
+    }
+    if (misgated.length > 0) {
+        warn('some extensions gate a trigger for an extension id that is not their own:');
+        bullets(misgated.map(describeMisgated));
+        info('  it is what a copied function leaves behind. The trigger deploys, fires on every write, and');
+        info('  the handler never runs — the gate asks about an extension nobody installed. Fix the id in');
+        info('  the forInstalledExtension call.');
+    }
+    if (problems.length > 0) {
         for (const claim of claims) {
             if (problems.some((problem) => problem.includes(claim.pluginId)))
                 rejected.add(claim.pluginId);
         }
+        // O dono de um portão errado é pendurado por IDENTIDADE, e não por o id dele aparecer no texto: a
+        // mensagem cita DOIS ids, e casar por substring penduraria também a extensão cujo id foi copiado.
+        for (const entry of misgated)
+            rejected.add(entry.owner);
     }
     const valid = uniqueByPlugin(claims.filter((claim) => !rejected.has(claim.pluginId)));
     /**
-     * Os índices são resolvidos ANTES do desvio de "nenhuma extensão exige nada" — e não depois, onde
-     * estavam. Desinstalar a única extensão com backend caía justamente naquele desvio, então o índice
-     * dela não era relatado por ninguém: o aviso existia para o caso de sobrar um órfão entre outras
-     * extensões, e faltava no caso de sobrar sozinho.
+     * O nome que uma reivindicação RECUSADA carrega. Ele não entra em `wantedFunctions` — não há como
+     * deployá-lo —, mas também não pode virar órfão: a extensão que o pede continua instalada, e o que
+     * falhou foi resolver a declaração dela. Sem esta lista, um export renomeado em
+     * `extensions/<x>/functions/index.ts` fazia `--prune` apagar a function de uma extensão viva.
      */
+    const unresolved = new Map();
+    for (const claim of claims) {
+        if (!rejected.has(claim.pluginId))
+            continue;
+        for (const name of claim.backend.functions ?? [])
+            unresolved.set(name, claim.pluginId);
+    }
     if (valid.length === 0) {
         info('  no installed extension asks for backend artifacts');
     }
@@ -113,14 +216,60 @@ export const provisionBackend = async (options) => {
         bullets(valid.map((claim) => `${claim.name} ${claim.version} (${claim.pluginId})`));
     }
     const settled = await settleIndexes(options, valid);
-    if (valid.length === 0) {
-        await recordBackendState(options, parseAppliedFunctions(options.environment.backend.functions), parseParameterState(options.environment.backend.parameters), settled.declared);
-        reportOrphanIndexes(projectId, settled.orphans, options.prune);
-        return outcome;
+    /**
+     * NÃO existe mais um desvio de "nenhuma extensão exige nada" aqui — e é a correção do defeito que
+     * este comando tinha justamente no caso mais comum. Desinstalar a ÚLTIMA extensão com backend caía
+     * naquele desvio, e o desvio devolvia antes do cálculo de órfã: a Cloud Function dela continuava no
+     * ar para sempre, `--prune` não a alcançava, e a lista de aplicadas era regravada intacta. O sintoma
+     * era um gatilho `onDocumentWritten` de uma extensão que ninguém tem mais, disparando sobre os dados
+     * do escritório a cada gravação.
+     *
+     * O índice já havia sido salvo dessa mesma armadilha — foi por isso que `settleIndexes` subiu para
+     * antes do desvio. A function ficou para trás, e a lição é que o desvio é que estava errado: o que
+     * ele pulava não era "trabalho inútil", era a retirada.
+     *
+     * O que sobrou dele são duas guardas pontuais mais abaixo: não perguntar ao projeto o que ele roda
+     * quando não há nada a conferir, e não anunciar que "as 0 functions já estão deployadas".
+     */
+    /**
+     * A function COMUM que declara quem serve entra aqui, e é o que a tira da invisibilidade.
+     *
+     * Ela não tem dono que possa reivindicá-la — nenhuma extensão pode —, então ela ficava fora do
+     * mecanismo por inteiro: nunca entrava no registro de aplicadas, nunca virava órfã, nunca era
+     * relatada, e o `--prune` não a alcançava. Com a declaração, a pergunta passa a ter resposta: ela é
+     * devida enquanto ALGUMA das extensões que ela serve estiver instalada em algum escritório do projeto.
+     *
+     * "Basta uma" é a única regra possível: a function existe porque mais de uma extensão precisa dela.
+     * Exigir todas faria desinstalar uma desligar o backend das outras.
+     */
+    const sharedWanted = office.served.filter((entry) => entry.serves.some((id) => survey.installedIds.has(id)));
+    const sharedWantedNames = new Set(sharedWanted.map((entry) => entry.name));
+    const wantedFunctions = deployable.filter((name) => sharedWantedNames.has(name)
+        || valid.some((claim) => (claim.backend.functions ?? []).includes(name)));
+    /** Quem reivindica cada nome AGORA — é com este dono que o registro é reconciliado. */
+    const owners = new Map();
+    for (const claim of valid) {
+        for (const name of claim.backend.functions ?? [])
+            owners.set(name, claim.pluginId);
     }
-    const wantedFunctions = deployable.filter((name) => valid.some((claim) => (claim.backend.functions ?? []).includes(name)));
-    const alreadyApplied = parseAppliedFunctions(options.environment.backend.functions);
-    const trackedParameters = claimedParameters(valid);
+    // A comum tem VÁRIOS donos, e o registro guarda a lista declarada em vez de eleger um deles: é ela que
+    // explica, meses depois, por que aquela function estava ali — e por que ela deixou de estar.
+    for (const entry of sharedWanted)
+        owners.set(entry.name, entry.serves.join('+'));
+    const applied = parseAppliedFunctions(options.environment.backend.functions);
+    const appliedNames = new Set(applied.map((entry) => entry.name));
+    const classification = classifyApplied({
+        applied,
+        wanted: wantedFunctions,
+        baseline: manifest.baselineFunctions ?? [],
+        unresolved,
+    });
+    // Os do diretório comum entram: são eles que as functions comuns servidas carregam, e um parâmetro
+    // que ninguém acompanha é um valor que nunca chega à function que o lê.
+    const trackedParameters = [...new Set([
+            ...claimedParameters(valid),
+            ...(office.sources.find((source) => source.shared)?.parameters ?? []).map((p) => p.name),
+        ])].sort();
     // A raiz, e não o `install/`: a fonte é o arquivo que o escritório edita ao lado do `microteia.yaml`.
     const filledParameters = await readBackendEnv(dirname(options.environmentFile), projectId);
     const recordedDigests = parseParameterState(options.environment.backend.parameters);
@@ -137,13 +286,47 @@ export const provisionBackend = async (options) => {
     // instalação fica sem nenhum comando que o aplique, e a feature falha no runtime.
     const changed = changedParameters(recordedDigests, currentDigests, trackedParameters);
     const staleFunctions = new Set(functionsDeclaringParameters(valid, changed)
-        .filter((name) => wantedFunctions.includes(name) && alreadyApplied.includes(name)));
-    // Uma pergunta só ao projeto, e duas decisões a partir dela: o que ele já roda, e qual cópia ficou
-    // numa região abandonada.
-    const deployedFunctions = await listDeployedFunctions(projectId);
+        .filter((name) => wantedFunctions.includes(name) && appliedNames.has(name)));
+    /**
+     * A comum que agora sobe pelo provisionamento também precisa voltar à fila quando um parâmetro muda.
+     * Antes ela subia a cada `deploy`, e isso mascarava a pergunta.
+     *
+     * A granularidade é o DIRETÓRIO, e não a function: `functions/` declara os `defineString` num conjunto
+     * só, sem dizer qual function lê qual. Redeployar todas as comuns servidas quando um parâmetro do
+     * diretório muda erra para o lado de fazer o que é devido — o inverso deixaria uma delas rodando com o
+     * valor antigo, que é o defeito que este mecanismo existe para fechar.
+     */
+    const sharedSource = office.sources.find((source) => source.shared);
+    const sharedParameters = new Set((sharedSource?.parameters ?? []).map((parameter) => parameter.name));
+    if (changed.some((name) => sharedParameters.has(name))) {
+        for (const entry of sharedWanted) {
+            if (appliedNames.has(entry.name))
+                staleFunctions.add(entry.name);
+        }
+    }
+    /**
+     * Uma pergunta só ao projeto, e duas decisões a partir dela: o que ele já roda, e qual cópia ficou
+     * numa região abandonada. Perguntar duas vezes não é caro, é ambíguo — as duas respostas podem
+     * divergir, e aí a decisão passa a depender de qual delas o código olhou.
+     *
+     * Ela é feita SEMPRE, e a versão anterior a pulava quando não havia function aplicada a conferir —
+     * economia que custava exatamente o caso que mais importa. É a instalação sem extensão nenhuma que
+     * precisa da pergunta: é ali que mora a function de uma extensão que saiu, e sem perguntar ao projeto
+     * a resposta é o silêncio. A ida vale segundos; a alternativa é uma callable órfã que nenhum comando
+     * menciona.
+     */
+    let asked;
+    const projectFunctions = async () => {
+        if (asked === undefined)
+            asked = await listDeployedFunctions(projectId);
+        return asked;
+    };
     // O que a lista de nomes nunca respondeu: a function aplicada que sumiu do projeto, e a que segue
     // lá carregando o carimbo de um código anterior. As duas voltam para a fila.
-    const outdated = outdatedByStamp(wantedFunctions.filter((name) => alreadyApplied.includes(name)), deployedFunctions, region, options.refreshedStamps);
+    const appliedAndWanted = wantedFunctions.filter((name) => appliedNames.has(name));
+    const outdated = appliedAndWanted.length === 0
+        ? { absent: [], stale: [] }
+        : outdatedByStamp(appliedAndWanted, await projectFunctions(), region, options.refreshedStamps);
     for (const name of [...outdated.absent, ...outdated.stale])
         staleFunctions.add(name);
     if (outdated.absent.length > 0) {
@@ -180,9 +363,31 @@ export const provisionBackend = async (options) => {
         info('  Cloud Function at ITS deploy, so a function already running keeps the previous one.');
         blank();
     }
-    const toDeploy = wantedFunctions.filter((name) => options.all === true || !alreadyApplied.includes(name) || staleFunctions.has(name));
+    const queued = wantedFunctions.filter((name) => options.all === true || !appliedNames.has(name) || staleFunctions.has(name));
+    /**
+     * A recusa do portão, cobrada de quem está na fila — e só dela.
+     *
+     * Ela sai da fila em vez de derrubar o comando, e as duas metades disso importam. Sair da fila é o que
+     * impede a function de ir para o ar agindo sobre escritório que não a instalou, que é o defeito
+     * inteiro. Não derrubar é o que deixa o resto acontecer: as outras extensões recebem o backend delas,
+     * os índices convergem, e `--prune` apaga a órfã. O comando termina em erro por causa dela, no fim,
+     * quando já não há nada a atrapalhar.
+     */
+    const refused = queued.filter((name) => gateFaultBy.has(name));
+    const toDeploy = queued.filter((name) => !gateFaultBy.has(name));
+    if (refused.length > 0) {
+        blank();
+        failure(`${refused.length} function(s) are needed by an installed extension and cannot go up:`);
+        bullets(refused.map((name) => gateFaultBy.get(name) ?? name));
+        info('  they are the only ones held back. Fix the guard and run "microteia provision" again.');
+        outcome.failed.push(...refused);
+    }
     if (toDeploy.length === 0) {
-        success(`the ${wantedFunctions.length} function(s) these extensions need are already deployed`);
+        // Anunciar "as 0 functions já estão deployadas" seria o preço de ter tirado o desvio, e não é
+        // preciso pagá-lo: quando não há exigência nenhuma, quem já falou foi a linha lá em cima.
+        if (wantedFunctions.length > 0 && refused.length === 0) {
+            success(`the ${wantedFunctions.length} function(s) these extensions need are already deployed`);
+        }
     }
     else {
         // A cópia que o `firebase-functions` lê é atualizada AGORA, e não só no `deploy`: este comando é o
@@ -199,18 +404,18 @@ export const provisionBackend = async (options) => {
         }
         // A extensão que mudou de região deixa a cópia antiga para trás igual ao kernel, e ali o efeito
         // é o mesmo: deploy recusado em toda tentativa, e gatilho disparando em duas regiões.
-        await clearRegionOrphans(projectId, toDeploy, region, options.prune, deployedFunctions);
+        await clearRegionOrphans(projectId, toDeploy, region, options.prune, await projectFunctions());
         info(`  deploying ${toDeploy.length} function(s), one at a time…`);
         const report = await deployFunctionsOneByOne(toDeploy, {
             projectId, cwd: install, delaySeconds, force: false,
         });
         outcome.deployed = report.deployed;
-        outcome.failed = report.failed.map((entry) => entry.name);
+        outcome.failed.push(...report.failed.map((entry) => entry.name));
         reportFailures(report.failed);
         reportNotices(report.notices);
         await checkNewCallables([...(manifest.callables ?? []), ...office.callables], report.deployed, projectId, region);
     }
-    const deployedNow = new Set([...alreadyApplied, ...outcome.deployed]);
+    const deployedNow = new Set([...appliedNames, ...outcome.deployed]);
     for (const claim of valid) {
         const satisfied = (claim.backend.functions ?? []).every((name) => deployedNow.has(name));
         if (satisfied) {
@@ -220,14 +425,49 @@ export const provisionBackend = async (options) => {
             outcome.pending.push(claim);
         }
     }
-    const orphans = alreadyApplied.filter((name) => !wantedFunctions.includes(name));
-    outcome.orphans = orphans;
-    const remaining = await settleOrphans(options, orphans);
+    /**
+     * O que o PROJETO roda, cruzado com o que esta instalação consegue justificar.
+     *
+     * O registro respondia sozinho por essa pergunta, e é um registro que se perde — e quando se perde,
+     * some com ele a única memória de que aquela function existe. Perguntar ao projeto é o que fecha o
+     * buraco: uma callable de extensão desinstalada, no ar, publicamente invocável, com o
+     * `backend.functions` do `microteia.yaml` vazio, não era mencionada por comando nenhum.
+     *
+     * O limite está em `straysInProject`, e é o que torna isto seguro: só vira órfã o nome que ESTA
+     * instalação sabe produzir. O que a órfã ganha aqui, além da remoção, é entrar no registro quando não
+     * for removida — a partir da próxima execução ela é conhecida mesmo que o código-fonte dela saia do
+     * disco.
+     */
+    const running = await projectFunctions();
+    const stray = straysInProject({
+        // A região é o filtro, e o ESTADO não é. Uma cópia em região abandonada tem endereço próprio
+        // (`clearRegionOrphans`); já o estado só decide se dá para comparar carimbo — para existir no
+        // projeto, basta estar na listagem. E o `functions:list` nem sempre traz o campo: exigir `ACTIVE`
+        // deixaria a varredura cega em silêncio no dia em que ele viesse vazio.
+        running: (running ?? []).filter((entry) => entry.region === region).map((entry) => entry.name),
+        known: [...manifest.functions, ...office.all],
+        justified: [
+            ...wantedFunctions,
+            // A baseline do PACOTE, com o mesmo fallback que o `deploy` usa para decidir o que subir. Um
+            // `?? []` aqui faria toda function da plataforma virar órfã num pacote sem o campo.
+            ...(manifest.baselineFunctions ?? manifest.functions),
+            ...office.unserved,
+            ...unresolved.keys(),
+        ],
+        recorded: applied.map((entry) => entry.name),
+    });
+    reportStrays(stray, running);
+    reportPreserved(classification.preserved);
+    const orphans = [...classification.orphans, ...stray.orphans];
+    outcome.orphans = orphans.map((entry) => entry.name);
+    const remaining = await settleOrphans(options, orphans, survey);
     await recordBackendState(options, appliedAfterRun({
-        alreadyApplied,
+        applied,
         wanted: wantedFunctions,
         deployed: outcome.deployed,
         keptOrphans: remaining,
+        preserved: classification.preserved.map((item) => item.entry),
+        owners,
     }), appliedParameterState({
         recorded: recordedDigests,
         current: currentDigests,
@@ -236,8 +476,37 @@ export const provisionBackend = async (options) => {
         claims: valid,
     }), settled.declared);
     reportOrphanIndexes(projectId, settled.orphans, options.prune);
+    await publishResidue(projectId, remaining, settled.orphans, survey);
     return outcome;
 };
+/**
+ * O que sobrou, devolvido ao banco para a aplicação poder mostrá-lo.
+ *
+ * A lista é a que sobra DEPOIS do `--prune`: o que ele apagou saiu, e o que ele não conseguiu apagar
+ * fica — é o estado do projeto agora, e não o do começo da execução.
+ *
+ * Falhar aqui não derruba o comando, e a exceção é justificada: as functions e os índices já foram
+ * aplicados, e o que ficou de fazer era um RELATO. Recusar o `provision` inteiro por causa dele mandaria
+ * quem instala rodar de novo um comando que já terminou o trabalho. Mas o aviso é dito em voz alta —
+ * calar deixaria a tela silenciosa parecendo "não há resíduo", que é a afirmação oposta.
+ */
+const publishResidue = async (projectId, functions, indexes, survey) => {
+    try {
+        await writeBackendResidue(projectId, {
+            scannedAt: new Date(),
+            tenants: survey.tenants,
+            extensions: survey.extensions,
+            functions: functions.map((entry) => ({ name: entry.name, owner: entry.owner ?? '' })),
+            indexes: indexes.map(describeIndex),
+        });
+    }
+    catch (error) {
+        warn('could not record what is left over where the application can show it:');
+        info(`  ${error instanceof Error ? error.message : String(error)}`);
+        info('  the artifacts above were applied. What did not happen is the Extensions screen learning');
+        info('  about the leftovers — it keeps showing what the previous run recorded.');
+    }
+};
 /**
  * O que o projeto tem de declarar de índice composto, e o que sobrou de uma extensão que saiu.
  *
@@ -320,34 +589,110 @@ const stampApplied = async (projectId, all, claim) => {
     success(`${claim.name} is ready in ${projectId}`);
 };
 /**
- * Function que nenhuma extensão instalada exige mais. Apagar é destrutivo e irreversível, então o
- * padrão RELATA e só `--prune` remove — e o que foi removido sai da lista de aplicadas.
+ * O que ninguém exige e mesmo assim NÃO é órfã.
+ *
+ * Relatar é o ponto. As duas causas são configuração errada de um lado ou do outro, e o silêncio sobre
+ * elas faria a próxima pessoa a abrir o `microteia.yaml` concluir que a lista está suja — e apagar à
+ * mão exatamente o que estas linhas protegem.
+ */
+const reportPreserved = (preserved) => {
+    const baseline = preserved.filter((item) => item.reason === 'baseline');
+    const unresolved = preserved.filter((item) => item.reason === 'unresolved');
+    if (baseline.length > 0) {
+        blank();
+        warn(`${baseline.length} function(s) in this installation's record belong to the platform:`);
+        bullets(baseline.map((item) => describeApplied(item.entry)));
+        info('  every "microteia deploy" puts them up, extension or no extension, so nothing here removes');
+        info('  them — not even --prune.');
+    }
+    if (unresolved.length > 0) {
+        blank();
+        warn(`${unresolved.length} function(s) belong to an extension whose declaration did not resolve:`);
+        bullets(unresolved.map((item) => `${item.entry.name} — claimed by ${item.claimant}`));
+        info('  the extension is still installed, so they are not orphans and nothing removes them.');
+        info('  Fix what is reported above and run "microteia provision" again.');
+    }
+};
+/**
+ * O que a varredura do projeto achou, e que o registro não conhecia.
+ *
+ * As duas listas são ditas porque respondem a perguntas diferentes de quem lê. A órfã é uma decisão a
+ * tomar — ela vai para `settleOrphans` logo abaixo, e sai com `--prune`. O estranho não é decisão
+ * nenhuma: é um aviso de que o projeto Firebase tem inquilino que a Microteia não pôs ali, e dizer que
+ * nada o toca vale mais do que o silêncio, porque o silêncio aqui parece "não há mais nada".
+ */
+const reportStrays = (stray, running) => {
+    if (running === null) {
+        blank();
+        warn('could not list what this project is running, so nothing was compared against it.');
+        info('  a function left behind by an extension that is gone would not be found this run. The');
+        info('  account needs permission to run "firebase functions:list".');
+        return;
+    }
+    if (stray.orphans.length > 0) {
+        blank();
+        info(`  ${stray.orphans.length} function(s) are running in this project and this installation's`);
+        info('  record does not mention them:');
+        bullets(stray.orphans.map((entry) => entry.name));
+        info('  this installation is what produces them, and nothing installed needs them — so they are');
+        info('  treated as orphans below. A record is lost by a re-init, a restored backup, or a Console');
+        info('  older than the field; the function it forgot stays in the air either way.');
+    }
+    if (stray.strangers.length > 0) {
+        blank();
+        info(`  ${stray.strangers.length} function(s) run in this project and did not come from this`);
+        info('  installation:');
+        bullets(stray.strangers);
+        info('  nothing here touches them — not even --prune. A Firebase project can be shared, and');
+        info('  deleting what Microteia did not put there is not this command\'s call.');
+        info('  A function of yours lands here once its source is gone from this installation: run');
+        info('  "microteia provision" BEFORE deleting extensions/<folder>/, and it is recognized.');
+    }
+};
+/**
+ * Function que nenhuma extensão instalada exige mais.
+ *
+ * A CERTEZA vem antes da remoção, e é dita em voz alta: a Cloud Function é do PROJETO e a instalação é
+ * do ESCRITÓRIO, então "ninguém mais exige" é uma afirmação sobre TODOS os escritórios do projeto, e
+ * não sobre o último que foi lido. A varredura é completa ou não existe — `listDocuments` pagina até o
+ * fim e qualquer leitura recusada derruba o comando lá em cima —, e é o número dito aqui que permite a
+ * quem lê conferir a afirmação em vez de acreditar nela.
+ *
+ * Apagar é destrutivo e irreversível, então o padrão RELATA e só `--prune` remove — e o que foi
+ * removido sai da lista de aplicadas.
  */
-const settleOrphans = async (options, orphans) => {
+const settleOrphans = async (options, orphans, survey) => {
     if (orphans.length === 0)
         return [];
     blank();
+    warn(`${orphans.length} function(s) are deployed and no installed extension needs them:`);
+    bullets(orphans.map(describeApplied));
+    info(`  read from every office in this project: ${survey.tenants} office(s), `
+        + `${survey.extensions} installed extension(s).`);
     if (!options.prune) {
-        warn(`${orphans.length} function(s) are deployed but no installed extension needs them:`);
-        bullets(orphans);
-        info('  they keep working and cost nothing while idle. To remove them:');
+        // O custo mudou de descrição porque a descrição estava errada. Uma callable ociosa não custa nada;
+        // um gatilho de Firestore não fica ocioso — ele segue disparando a cada gravação do escritório,
+        // rodando o código de uma extensão que ninguém tem mais, e é esse efeito que faz a remoção valer
+        // a pena antes de "algum dia".
+        info('  a callable just sits there. A Firestore trigger does not: it keeps firing on every write,');
+        info('  running the code of an extension nobody has any more. To remove them:');
         bullets(['microteia provision --prune']);
         blank();
         return orphans;
     }
     info(`  deleting ${orphans.length} orphan function(s)…`);
-    const deleted = [];
-    for (const name of orphans) {
+    const deleted = new Set();
+    for (const orphan of orphans) {
         try {
-            await run(FIREBASE_BIN, ['functions:delete', name, '--project', options.projectId, '--region', options.region, '--force'], { cwd: options.install });
-            deleted.push(name);
+            await run(FIREBASE_BIN, ['functions:delete', orphan.name, '--project', options.projectId, '--region', options.region, '--force'], { cwd: options.install });
+            deleted.add(orphan.name);
         }
         catch {
-            warn(`could not delete ${name}; it stays recorded as deployed`);
+            warn(`could not delete ${orphan.name}; it stays recorded as deployed`);
         }
     }
-    success(`${deleted.length} orphan function(s) removed`);
-    return orphans.filter((name) => !deleted.includes(name));
+    success(`${deleted.size} orphan function(s) removed`);
+    return orphans.filter((orphan) => !deleted.has(orphan.name));
 };
 /**
  * Índice órfão é RELATADO, nunca apagado às cegas: o `firebase deploy` não remove índice por conta, e a
@@ -380,16 +725,6 @@ const reportOrphanIndexes = (projectId, orphans, prune) => {
     ]);
     blank();
 };
-/**
- * A lista aplicada CONVERGE para o que ainda é exigido: o que já estava e continua sendo pedido, mais
- * o que subiu agora, mais o órfão que não foi removido. Reescrevê-la só com o que subiu NESTA execução
- * a esvaziava na segunda passada — e a terceira redeployava tudo, achando que nada havia sido feito.
- */
-export const appliedAfterRun = (input) => [...new Set([
-        ...input.alreadyApplied.filter((name) => input.wanted.includes(name)),
-        ...input.deployed,
-        ...input.keptOrphans,
-    ])].sort();
 /**
  * A impressão digital do parâmetro só avança quando TODAS as functions que o carregam subiram. Gravar
  * antes disso é o que transformaria uma falha de deploy em silêncio permanente: o valor novo ficaria
@@ -414,7 +749,7 @@ export const appliedParameterState = (input) => {
     }
     return next;
 };
-const recordBackendState = async (options, names, parameters, indexes) => {
+const recordBackendState = async (options, applied, parameters, indexes) => {
     const state = serializeIndexState(indexes);
     /**
      * Índice que a codificação não representa sem ambiguidade fica de fora COM AVISO, em vez de voltar do
@@ -431,7 +766,7 @@ const recordBackendState = async (options, names, parameters, indexes) => {
     await writeEnvironment(options.environmentFile, {
         ...options.environment,
         backend: {
-            functions: names.length === 0 ? null : names.join(','),
+            functions: serializeAppliedFunctions(applied),
             parameters: serializeParameterState(parameters),
             indexes: state.value,
         },