@microteia/console 2.10.0 → 2.19.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,63 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.19.0] — 2026-08-28
+
+- fix(cli/deploy): the installation gate is charged against the functions that are GOING UP, not against every source found on disk. It lived in `functionProblems` — the door that answers "can this set be assembled?" — and that door reads every `extensions/<x>/functions/` directory that exists, including one left behind by an extension that was uninstalled and removed. The result was `microteia deploy` refusing in full — hosting, rules and indexes with it — over a callable no command would have deployed. `gateProblems` now carries the function's name, and `gateProblemsFor` filters by what is being deployed.
+- fix(cli/provision): a gated function that fails the check leaves the deploy queue instead of taking the command down with it. Everything else provisions, `--prune` still removes the orphan, and the command ends in an error naming the function that was held back.
+- feat(cli/provision): orphan functions are found in the PROJECT, not only in the record. `backend.functions` in `microteia.yaml` was the single source of truth about what had been deployed, and it is a truth that gets lost — a redone `init`, a restored backup, a Console older than the field. Lost it, and the Cloud Function of an extension nobody has stayed in the air with no command mentioning it. `straysInProject` crosses `firebase functions:list` with what the installation can justify; only a name this installation knows how to produce can become an orphan, and what it does not know is reported and never touched.
+- feat(cli/provision): an orphan found that way enters the record when it is not removed, so it stays known from the next run on even if its source leaves the disk.
+- fix(cli/provision): `functions:list` is asked on every run. It was skipped when there was nothing applied to check — the exact case that needed it, since an installation with no extensions left is where the departed extension's function sits. When the listing cannot be read, the command says so instead of letting silence read as "nothing left over".
+
+#### [2.18.0] — 2026-08-28
+
+- feat(console/functionGate): an extension's callable without `requireInstalledExtension` is refused, and a guard naming another extension's id is rejected the way a misgated trigger is. The refusal exists because the deploy makes every callable publicly invocable — this Console's own `callableAccess.ts` is there to confirm that grant went through — so the callable answers any signed-in user of the project, from any organization, whether or not they installed the extension, with the organization arriving in the payload.
+- feat(console/functionGate): the scope of this check is the FILE, like the per-office loop and unlike the trigger guard. The guard runs inside the handler because it needs the `request`, and the authoring guide asks authors to keep the handler thin with the decision in a file beside it — demanding the call inside the parentheses would refuse exactly the code the guide asks for.
+- feat(console/functionGate): the SHARED callable is left out, and it is recorded rather than silently skipped: `requireInstalledExtension` takes one id and a shared function serves several. The "any of the ones I serve" guard exists for a trigger (`forAnyInstalledExtension`), not for a callable.
+
+#### [2.17.0] — 2026-08-28
+
+- feat(console/customFunctions): `microteia.serves` in `functions/package.json` — function name to the extension ids it serves. It closes the widest and quietest gap in the whole withdrawal mechanism. A function in `functions/` has no owner by construction (no extension may claim it), so it sat outside the mechanism ENTIRELY: never recorded as applied, never classified as an orphan, never reported, and out of `--prune`'s reach. It stayed deployed forever, put up by every deploy, with every extension it served long uninstalled — and the authoring guide was the thing telling authors to put shared functions there.
+- feat(console/provision): a shared function that declares who it serves is deployed while ANY of them is installed anywhere in the project, and becomes an orphan when none is. The question is asked against every active installation and not against the claims: an extension with no `manifest.backend` never becomes a claim, and could well be one of the served ones — deciding from the claim list would delete the function of somebody who has it installed. The applied record keeps the declared list rather than electing one owner, because that is what explains, months later, why the function was there and why it stopped being.
+- feat(console/deploy): a shared function that declares who it serves leaves the unconditional deploy list. Putting it up here anyway would have `--prune` delete it and the next deploy restore it, indefinitely — the same loop the claim refusal avoids. One with NO declaration goes up exactly as before: keeping that is what stops this version from taking a function out of an installation that already works.
+- feat(console/functionGate): a declared shared trigger without a guard is refused, and so is a guard naming an extension the function does not declare serving. The two lists answer the same question — `serves` decides the withdrawal, the guard decides the execution — and one of them being wrong makes the function act where it can no longer be withdrawn. Guarding by one of the declared extensions is accepted: the list is the ceiling, not the floor. A shared function with no `serves` is not asked for a guard, because without ids there would be no guard to ask for.
+- feat(console/provision): shared functions with no `serves` are listed on every run. They keep working as before and nothing withdraws them — what changes is that they stop being invisible, which was the defect: whoever inherited an installation had no way to know those functions were outside the mechanism, and the only way to find out was a trigger firing years after the last extension that used it had gone.
+- fix(console/provision): a parameter declared in `functions/` now marks the served shared functions as stale. They used to go up on every deploy, which masked the question; moving them to provisioning would have left one running with the old value, which is the defect that mechanism exists to close. The granularity is the directory, not the function, because `functions/` declares its `defineString` calls in one set without saying which function reads which.
+
+#### [2.16.0] — 2026-08-28
+
+- feat(console/functionGate): an extension's function whose event carries no `{tenantId}` — `onSchedule`, `onMessagePublished`, `onRequest`, the Storage object triggers, the login-blocking ones — is refused unless it loops with `forEachInstalledOffice`. The refusal only became honest once there was an answer to point at: before it, both of the author's options were wrong, and the worse one passed every check. A loop naming another extension's id is rejected the same way a misgated trigger is, and the report names WHICH guard got the wrong id, because the fix is in one string and the author should not have to guess which.
+- feat(console/functionGate): the scope of this check is the FILE, not the call's parentheses. A document trigger's guard wraps that handler, so it has to be there; the loop runs inside the handler and may sit a couple of calls deeper, in a helper the author wrote. Demanding it in the parentheses would refuse correct code, and the price is stated: two scheduled functions in one file, one looping and one not, both pass.
+- feat(console/functionGate): the list of constructors is explicit rather than "everything that is not a document trigger". RTDB is deliberately left out — its path HAS parameters, so a `{tenantId}` there is possible, and the platform uses no RTDB anywhere. What is not known is not refused.
+
+#### [2.15.0] — 2026-08-28
+
+- feat(console/backendResidue): provisioning writes what it found back to the database, at `backend_state/current`. It is the one place in the system that can say "this Cloud Function has no owner any more" — the answer needs a scan of every office in the project compared against the applied record — and it said so in the terminal and kept the conclusion in `microteia.yaml`, a file on one operator's machine. The application never learned anything, so the whole mechanism depended on somebody remembering. This is not a new path: the Console already writes to the database over REST, which is how `backendState` is stamped.
+- feat(console/backendResidue): the document is written on EVERY run, empty included. Writing only when there are orphans would leave the banner up after `--prune` had already dealt with them, and a banner that never goes away is one people learn to ignore — the empty list is what clears the previous one. The list is the one left AFTER pruning: what it deleted is gone, what it could not delete stays, which is the state of the project now rather than the state at the start of the run. `tenants` and `extensions` travel with it, because "nobody needs it any more" is a claim about every office in the project and whoever reads the banner deserves to check it instead of believing it.
+- fix(console/provision): failing to record the leftovers does not fail the command. The functions and indexes were already applied; what was left to do was a REPORT, and refusing the whole run would send whoever installs to repeat a command that finished its work. The failure is said out loud, though — staying quiet would leave a silent screen looking like "there is no residue", which is the opposite claim.
+- feat(console/firestoreRest): `asInteger`, `asArray`, `asMap` and `patchFields`. The mask lists every field written, deliberately: without it a PATCH behaves differently depending on whether the document exists, and what is wanted here is convergence — since all fields are written every time, the complete mask is also what erases what stopped being true.
+
+#### [2.14.0] — 2026-08-28
+
+- feat(console/provision): claiming a function that lives in `functions/` — the directory for a function SEVERAL extensions share — is refused. `baselineClaimProblems` already guarded the same defect against the platform's own functions, and the sentence is identical: the deploy puts it up regardless, so the claim changes nothing while the extension is installed, and the day it is uninstalled `--prune` deletes a function other extensions depended on. This case adds one turn of the screw — the next deploy puts it back, because the source is still sitting in `functions/` — so the symptom is an outage that closes by itself, repeating on every `provision --prune`, with nothing in the tree to suggest what happened. Rejecting the extension puts the name in `unresolved`, which is what keeps `--prune` off the shared function while the wrong declaration stands.
+
+#### [2.13.0] — 2026-08-28
+
+- feat(console/functionGate): an extension's Firestore trigger without `forInstalledExtension` is refused. The guard is the half of the withdrawal that acts at the moment somebody clicks Uninstall — `--prune` cannot reach the office that uninstalled while another still has the extension — and nothing cobbled it: `create function` wrote it into the scaffold, and no check in packing, deploying or provisioning ever read the source again. An ungated trigger went up and stayed up, and its symptom is not a failure: it is the code of an extension nobody has any more running over the data of offices that never asked for it, with no error anywhere.
+- feat(console/provision): a guard that names ANOTHER extension's id rejects the extension that claims the function. It is what a copied function leaves behind, and its symptom is the opposite of the ungated one — the trigger deploys, fires on every write, and the handler never runs, because the gate asks about an extension nobody installed. Only provisioning can ask this: the claim comes from the office's database, and the deploy does not have it. The owner is rejected by identity and not by substring, because the message names two ids and matching on text would also reject the extension whose id was copied.
+- feat(console/provision): an ungated trigger already deployed is REPORTED rather than refused. Refusing here would lock `--prune` — the one command that removes the orphan — behind a source it does not need to read. The refusal belongs where the source enters the package, and there it blocks nobody's way out.
+- fix(console/functionGate): comments are stripped before the source is read, and strings are not. The scaffold's own JSDoc cites `forInstalledExtension` to explain it, so deleting the call and keeping the explanation would have passed the check — which is exactly what an author produces while editing generated code. A guard declared in an identifier beside the trigger is accepted, because that is correct code and a check that refuses correct code is the one that teaches the next person to switch it off.
+
+#### [2.12.0] — 2026-08-27
+
+- feat(pack): the packaged `functions/package.json` gains an `exports` map and `custom/tsconfig.json` a `paths` entry, which is what lets a Cloud Function written by the organization import `microteia-functions/office` — the platform surface that keeps an extension's trigger from running in organizations that do not have it. No new dependency, so the packaged lockfile stays valid.
+
+#### [2.11.0] — 2026-08-27
+
+- fix(provision): orphan Cloud Functions are reported even when no installed extension asks for a backend at all — the case that mattered most, and the only one the previous shortcut skipped.
+- fix(provision --prune): a function claimed by an extension that is still installed, and one the platform deploys itself, are never deleted. Both were reachable before.
+- feat(provision): the record of applied functions carries the plugin that owns each one, and the orphan report names it along with how many offices were read to reach the conclusion.
+
 #### [2.10.0] — 2026-08-27
 
 - feat(export-catalog): a new command writes what an office HAS — its screens with their fields, its

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.10.0
+# Microteia Console 2.19.0
 
 Installs and updates Microteia in a Firebase project you own. It has no npm dependencies of its own —
 what it needs are command-line tools that are already on the machine, listed at the bottom.

package/lib/console/appliedFunctions.d.ts

@@ -0,0 +1,114 @@
+/**
+ * O registro do que o provisionamento já deployou — e de QUEM.
+ *
+ * Ele morava como uma lista de nomes soltos em `backend.functions` do `microteia.yaml`, e a lista de
+ * nomes nunca respondeu à única pergunta que a remoção faz: de quem era esta function? Sem o dono, o
+ * relatório de uma órfã é "sobrou `acmeSync`", que não é uma decisão — é um enigma para quem herda a
+ * instalação meses depois. Com o dono ele é "`acmeSync` era de `com.acme.crm`, que não está instalada
+ * em escritório nenhum", que é.
+ *
+ * A forma gravada é `nome@pluginId`, separada por vírgula, no mesmo escalar de antes. Uma entrada sem
+ * `@` continua sendo lida: é o que uma instalação anterior a este campo gravou, e ela vale — o que
+ * falta é o dono, não a function.
+ */
+export interface AppliedFunction {
+    name: string;
+    /** O plugin que a reivindicava quando ela subiu. `null` numa instalação anterior ao campo. */
+    owner: string | null;
+}
+export declare const parseAppliedFunctions: (raw: string | null) => AppliedFunction[];
+export declare const serializeAppliedFunctions: (applied: AppliedFunction[]) => string | null;
+/** Por que uma function que ninguém exige mais NÃO é órfã. */
+export type PreservedReason = 'baseline' | 'unresolved';
+export interface PreservedFunction {
+    entry: AppliedFunction;
+    reason: PreservedReason;
+    /** O plugin cuja declaração não pôde ser resolvida — só em `unresolved`. */
+    claimant?: string;
+}
+export interface AppliedClassification {
+    /** Alguma extensão instalada continua exigindo. */
+    wanted: AppliedFunction[];
+    /** Ninguém exige, e nada impede de remover. */
+    orphans: AppliedFunction[];
+    /** Ninguém exige, e remover seria errado. */
+    preserved: PreservedFunction[];
+}
+/**
+ * O que fazer com cada function já aplicada, e a razão de nunca ser só "ninguém pediu".
+ *
+ * As duas categorias preservadas existem porque "ninguém exige" tem três causas diferentes, e uma
+ * delas — a única — autoriza apagar:
+ *
+ * - `baseline`: a function é da PLATAFORMA. O `deploy` a sobe sempre, independentemente de extensão
+ *   nenhuma. Ela só chegou a este registro porque uma extensão reivindicou um nome do kernel, e apagá-la
+ *   derrubaria um gatilho do produto num escritório que não fez nada de errado.
+ * - `unresolved`: a extensão que a reivindica CONTINUA instalada, e o que falhou foi resolver a
+ *   declaração dela — um export renomeado em `extensions/<x>/functions/index.ts`, um upgrade que tirou o
+ *   nome do pacote. Apagar aqui é apagar a function de uma extensão viva por causa de um defeito de
+ *   configuração que a próxima execução conserta.
+ * - órfã de verdade: nome nenhum a reivindica, e nenhuma das duas condições acima vale. Foi
+ *   desinstalada de todos os escritórios do projeto.
+ */
+export declare const classifyApplied: (input: {
+    applied: AppliedFunction[];
+    wanted: string[];
+    baseline: string[];
+    /** Nome de function -> plugin cuja reivindicação foi recusada nesta execução. */
+    unresolved: Map<string, string>;
+}) => AppliedClassification;
+/**
+ * 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, mais o que foi preservado. 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.
+ *
+ * O dono é reconciliado com quem reivindica AGORA: uma function que trocou de extensão entre duas
+ * versões fica registrada com a atual, e não com a que a pôs no ar da primeira vez.
+ */
+export declare const appliedAfterRun: (input: {
+    applied: AppliedFunction[];
+    wanted: string[];
+    deployed: string[];
+    keptOrphans: AppliedFunction[];
+    preserved: AppliedFunction[];
+    /** Nome de function -> plugin que a reivindica nesta execução. */
+    owners: Map<string, string>;
+}) => AppliedFunction[];
+/** Como uma function aplicada aparece num relatório: sem dono conhecido, só o nome. */
+export declare const describeApplied: (entry: AppliedFunction) => string;
+export interface StrayFunctions {
+    /** Roda no projeto, esta instalação sabe produzi-la, e nada a justifica agora: órfã de verdade. */
+    orphans: AppliedFunction[];
+    /** Roda no projeto e esta instalação não a conhece. Relatada, nunca apagada. */
+    strangers: string[];
+}
+/**
+ * A órfã que o REGISTRO não conhece — e o limite que impede a varredura de virar um estrago.
+ *
+ * O registro (`backend.functions` do `microteia.yaml`) era a ÚNICA verdade sobre o que havia sido
+ * deployado, e é uma verdade que se perde: um Console anterior ao campo, um `init` refeito, um deploy
+ * dado à mão, um arquivo restaurado de um backup mais velho. Perdido o registro, `classifyApplied` não
+ * tinha o que classificar, `--prune` não tinha o que apagar, e a Cloud Function de uma extensão que
+ * ninguém tem mais ficava no ar para sempre, sem nenhum comando que a mencionasse. É o pior sintoma da
+ * família: uma callable publicamente invocável, de código que ninguém instalou, e silêncio.
+ *
+ * A resposta é perguntar ao PROJETO o que ele roda, em vez de só ao arquivo. E o limite é `known`: só é
+ * candidata a órfã a function que ESTA instalação sabe produzir — o que o pacote traz mais o que o
+ * escritório escreveu. O que o projeto roda e a instalação não conhece pode ser de qualquer um: um
+ * projeto Firebase é compartilhável, e apagar ali seria a Microteia decidir sobre o que não é dela.
+ * Esse caso é relatado e nunca tocado.
+ *
+ * `recorded` sai do resultado porque quem responde por ele é `classifyApplied`, que sabe mais: ele tem o
+ * dono e as duas razões de preservação. Contar duas vezes a mesma function proporia apagá-la duas vezes.
+ */
+export declare const straysInProject: (input: {
+    /** O que o projeto roda AGORA, na região do kernel. */
+    running: string[];
+    /** O que esta instalação sabe produzir: o pacote mais o que o escritório escreveu. */
+    known: string[];
+    /** O que tem razão de estar no ar agora: exigida, baseline, comum sem declaração, ou não resolvida. */
+    justified: string[];
+    /** O que o registro já conhece — respondido por `classifyApplied`. */
+    recorded: string[];
+}) => StrayFunctions;

package/lib/console/appliedFunctions.js

@@ -0,0 +1,123 @@
+export const parseAppliedFunctions = (raw) => {
+    const applied = [];
+    const seen = new Set();
+    for (const entry of (raw ?? '').split(',')) {
+        const trimmed = entry.trim();
+        if (trimmed === '')
+            continue;
+        const separator = trimmed.indexOf('@');
+        const name = separator === -1 ? trimmed : trimmed.slice(0, separator).trim();
+        const owner = separator === -1 ? '' : trimmed.slice(separator + 1).trim();
+        if (name === '' || seen.has(name))
+            continue;
+        seen.add(name);
+        applied.push({ name, owner: owner === '' ? null : owner });
+    }
+    return applied;
+};
+export const serializeAppliedFunctions = (applied) => {
+    const entries = [...applied]
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((entry) => (entry.owner === null ? entry.name : `${entry.name}@${entry.owner}`));
+    return entries.length === 0 ? null : entries.join(',');
+};
+/**
+ * O que fazer com cada function já aplicada, e a razão de nunca ser só "ninguém pediu".
+ *
+ * As duas categorias preservadas existem porque "ninguém exige" tem três causas diferentes, e uma
+ * delas — a única — autoriza apagar:
+ *
+ * - `baseline`: a function é da PLATAFORMA. O `deploy` a sobe sempre, independentemente de extensão
+ *   nenhuma. Ela só chegou a este registro porque uma extensão reivindicou um nome do kernel, e apagá-la
+ *   derrubaria um gatilho do produto num escritório que não fez nada de errado.
+ * - `unresolved`: a extensão que a reivindica CONTINUA instalada, e o que falhou foi resolver a
+ *   declaração dela — um export renomeado em `extensions/<x>/functions/index.ts`, um upgrade que tirou o
+ *   nome do pacote. Apagar aqui é apagar a function de uma extensão viva por causa de um defeito de
+ *   configuração que a próxima execução conserta.
+ * - órfã de verdade: nome nenhum a reivindica, e nenhuma das duas condições acima vale. Foi
+ *   desinstalada de todos os escritórios do projeto.
+ */
+export const classifyApplied = (input) => {
+    const wantedNames = new Set(input.wanted);
+    const baseline = new Set(input.baseline);
+    const classification = { wanted: [], orphans: [], preserved: [] };
+    for (const entry of input.applied) {
+        if (wantedNames.has(entry.name)) {
+            classification.wanted.push(entry);
+            continue;
+        }
+        if (baseline.has(entry.name)) {
+            classification.preserved.push({ entry, reason: 'baseline' });
+            continue;
+        }
+        const claimant = input.unresolved.get(entry.name);
+        if (claimant !== undefined) {
+            classification.preserved.push({ entry, reason: 'unresolved', claimant });
+            continue;
+        }
+        classification.orphans.push(entry);
+    }
+    return classification;
+};
+/**
+ * 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, mais o que foi preservado. 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.
+ *
+ * O dono é reconciliado com quem reivindica AGORA: uma function que trocou de extensão entre duas
+ * versões fica registrada com a atual, e não com a que a pôs no ar da primeira vez.
+ */
+export const appliedAfterRun = (input) => {
+    const wanted = new Set(input.wanted);
+    const byName = new Map();
+    const remember = (name, recorded) => {
+        byName.set(name, { name, owner: input.owners.get(name) ?? recorded });
+    };
+    for (const entry of input.applied) {
+        if (wanted.has(entry.name))
+            remember(entry.name, entry.owner);
+    }
+    for (const name of input.deployed)
+        remember(name, byName.get(name)?.owner ?? null);
+    for (const entry of [...input.keptOrphans, ...input.preserved])
+        remember(entry.name, entry.owner);
+    return [...byName.values()].sort((left, right) => left.name.localeCompare(right.name));
+};
+/** Como uma function aplicada aparece num relatório: sem dono conhecido, só o nome. */
+export const describeApplied = (entry) => entry.owner === null ? entry.name : `${entry.name} (${entry.owner})`;
+/**
+ * A órfã que o REGISTRO não conhece — e o limite que impede a varredura de virar um estrago.
+ *
+ * O registro (`backend.functions` do `microteia.yaml`) era a ÚNICA verdade sobre o que havia sido
+ * deployado, e é uma verdade que se perde: um Console anterior ao campo, um `init` refeito, um deploy
+ * dado à mão, um arquivo restaurado de um backup mais velho. Perdido o registro, `classifyApplied` não
+ * tinha o que classificar, `--prune` não tinha o que apagar, e a Cloud Function de uma extensão que
+ * ninguém tem mais ficava no ar para sempre, sem nenhum comando que a mencionasse. É o pior sintoma da
+ * família: uma callable publicamente invocável, de código que ninguém instalou, e silêncio.
+ *
+ * A resposta é perguntar ao PROJETO o que ele roda, em vez de só ao arquivo. E o limite é `known`: só é
+ * candidata a órfã a function que ESTA instalação sabe produzir — o que o pacote traz mais o que o
+ * escritório escreveu. O que o projeto roda e a instalação não conhece pode ser de qualquer um: um
+ * projeto Firebase é compartilhável, e apagar ali seria a Microteia decidir sobre o que não é dela.
+ * Esse caso é relatado e nunca tocado.
+ *
+ * `recorded` sai do resultado porque quem responde por ele é `classifyApplied`, que sabe mais: ele tem o
+ * dono e as duas razões de preservação. Contar duas vezes a mesma function proporia apagá-la duas vezes.
+ */
+export const straysInProject = (input) => {
+    const known = new Set(input.known);
+    const justified = new Set(input.justified);
+    const recorded = new Set(input.recorded);
+    const stray = { orphans: [], strangers: [] };
+    for (const name of [...new Set(input.running)].sort()) {
+        if (!known.has(name)) {
+            stray.strangers.push(name);
+            continue;
+        }
+        if (justified.has(name) || recorded.has(name))
+            continue;
+        stray.orphans.push({ name, owner: null });
+    }
+    return stray;
+};

package/lib/console/backendResidue.d.ts

@@ -0,0 +1,55 @@
+import type { FirestoreTypedValue } from './firestoreRest.js';
+/**
+ * O que o provisionamento descobriu, devolvido para o banco — onde a APLICAÇÃO pode ler.
+ *
+ * O `provision` é o único ponto do sistema capaz de dizer "esta Cloud Function não tem mais dono": a
+ * resposta exige varrer todos os escritórios do projeto e comparar com o registro de aplicadas. Ele
+ * dizia isso no terminal e guardava a conclusão no `microteia.yaml` — um arquivo na máquina de quem
+ * rodou o comando. Quem clicou em Desinstalar, na aplicação, nunca ficava sabendo de nada; e quem lê a
+ * tela de Extensões não é necessariamente quem tem acesso ao projeto Firebase.
+ *
+ * O efeito era o mesmo em toda instalação: o `--prune` continua sendo um ato explícito — e isso está
+ * certo, apagar é destrutivo e irreversível —, mas ninguém tinha como saber que ele era necessário. O
+ * mecanismo inteiro dependia de alguém lembrar.
+ *
+ * A tela de Extensões já mostra o selo "Backend pendente" para o caso da INSTALAÇÃO. Este documento é o
+ * par que faltava, o da RETIRADA, e não inventa caminho novo: o Console já escreve no banco pela REST
+ * (é assim que `backendState` é carimbado), e o pacote já tem uma coleção global de espelho somente
+ * leitura escrita só com credencial de administrador (`workflow_step_catalog`).
+ */
+/**
+ * Um documento só, de nome fixo. A órfã é um fato do PROJETO — não de um escritório —, então guardá-la
+ * por tenant seria guardar a mesma resposta N vezes e deixar N maneiras de ela divergir.
+ */
+export declare const BACKEND_RESIDUE_PATH = "/backend_state/current";
+export interface OrphanFunctionRecord {
+    name: string;
+    /** O plugin que a reivindicava quando ela subiu. Vazio numa instalação anterior ao registro com dono. */
+    owner: string;
+}
+export interface BackendResidueInput {
+    /** Quando a varredura aconteceu. É o que permite a quem lê saber se a informação é de hoje. */
+    scannedAt: Date;
+    /** Escritórios lidos, e cópias de extensão lidas: a contagem que SUSTENTA a afirmação. */
+    tenants: number;
+    extensions: number;
+    functions: OrphanFunctionRecord[];
+    /** O índice órfão, na forma legível que o relatório do terminal também usa. */
+    indexes: string[];
+}
+/**
+ * Os campos do documento, montados sem tocar na rede.
+ *
+ * Separado da escrita porque é a FORMA que é contrato: ela é lida pelo kernel, que é versionado à parte
+ * do Console. Um campo renomeado aqui é uma tela que deixa de avisar, em silêncio — e é essa a
+ * verificação que o teste faz.
+ */
+export declare const backendResidueFields: (input: BackendResidueInput) => Record<string, FirestoreTypedValue>;
+/**
+ * Escreve o resíduo, SEMPRE — inclusive quando não há nenhum.
+ *
+ * Escrever só quando há órfã deixaria o aviso na tela depois de o `--prune` já ter resolvido, e um aviso
+ * que não sai é um aviso que se aprende a ignorar. Como todos os campos são escritos a cada execução, a
+ * lista vazia é o que apaga a anterior.
+ */
+export declare const writeBackendResidue: (projectId: string, input: BackendResidueInput) => Promise<void>;

package/lib/console/backendResidue.js

@@ -0,0 +1,53 @@
+import { asArray, asInteger, asMap, asString, asTimestamp, patchFields } from './firestoreRest.js';
+import { CLI_VERSION } from '../shared/paths.js';
+/**
+ * O que o provisionamento descobriu, devolvido para o banco — onde a APLICAÇÃO pode ler.
+ *
+ * O `provision` é o único ponto do sistema capaz de dizer "esta Cloud Function não tem mais dono": a
+ * resposta exige varrer todos os escritórios do projeto e comparar com o registro de aplicadas. Ele
+ * dizia isso no terminal e guardava a conclusão no `microteia.yaml` — um arquivo na máquina de quem
+ * rodou o comando. Quem clicou em Desinstalar, na aplicação, nunca ficava sabendo de nada; e quem lê a
+ * tela de Extensões não é necessariamente quem tem acesso ao projeto Firebase.
+ *
+ * O efeito era o mesmo em toda instalação: o `--prune` continua sendo um ato explícito — e isso está
+ * certo, apagar é destrutivo e irreversível —, mas ninguém tinha como saber que ele era necessário. O
+ * mecanismo inteiro dependia de alguém lembrar.
+ *
+ * A tela de Extensões já mostra o selo "Backend pendente" para o caso da INSTALAÇÃO. Este documento é o
+ * par que faltava, o da RETIRADA, e não inventa caminho novo: o Console já escreve no banco pela REST
+ * (é assim que `backendState` é carimbado), e o pacote já tem uma coleção global de espelho somente
+ * leitura escrita só com credencial de administrador (`workflow_step_catalog`).
+ */
+/**
+ * Um documento só, de nome fixo. A órfã é um fato do PROJETO — não de um escritório —, então guardá-la
+ * por tenant seria guardar a mesma resposta N vezes e deixar N maneiras de ela divergir.
+ */
+export const BACKEND_RESIDUE_PATH = '/backend_state/current';
+/**
+ * Os campos do documento, montados sem tocar na rede.
+ *
+ * Separado da escrita porque é a FORMA que é contrato: ela é lida pelo kernel, que é versionado à parte
+ * do Console. Um campo renomeado aqui é uma tela que deixa de avisar, em silêncio — e é essa a
+ * verificação que o teste faz.
+ */
+export const backendResidueFields = (input) => ({
+    scannedAt: asTimestamp(input.scannedAt),
+    consoleVersion: asString(CLI_VERSION),
+    tenants: asInteger(input.tenants),
+    extensions: asInteger(input.extensions),
+    orphanFunctions: asArray(input.functions.map((entry) => asMap({
+        name: asString(entry.name),
+        owner: asString(entry.owner),
+    }))),
+    orphanIndexes: asArray(input.indexes.map((entry) => asString(entry))),
+});
+/**
+ * Escreve o resíduo, SEMPRE — inclusive quando não há nenhum.
+ *
+ * Escrever só quando há órfã deixaria o aviso na tela depois de o `--prune` já ter resolvido, e um aviso
+ * que não sai é um aviso que se aprende a ignorar. Como todos os campos são escritos a cada execução, a
+ * lista vazia é o que apaga a anterior.
+ */
+export const writeBackendResidue = async (projectId, input) => {
+    await patchFields(projectId, BACKEND_RESIDUE_PATH, backendResidueFields(input));
+};

package/lib/console/customFunctions.d.ts

@@ -1,4 +1,5 @@
 import type { BackendParameter } from '../kernel/manifest.js';
+import type { TriggerDeclaration } from './functionGate.js';
 /**
  * As Cloud Functions do ESCRITÓRIO — as que ele escreve, não as do kernel.
  *
@@ -37,10 +38,35 @@ export interface FunctionSource {
     shared: boolean;
     /** As callables — as únicas que o navegador chama, e por isso as únicas com alcance a conferir. */
     callables: string[];
+    /**
+     * As callables com o estado da guarda de instalação de cada uma. Separado de `callables` porque
+     * responde a outra pergunta: aquela é "o navegador alcança?", esta é "quem mais alcança?".
+     */
+    callableGuards: TriggerDeclaration[];
+    /**
+     * Os gatilhos de Firestore declarados aqui, com o estado do portão de instalação de cada um. É o que
+     * permite recusar um gatilho de extensão que dispararia para todos os escritórios do projeto.
+     */
+    triggers: TriggerDeclaration[];
+    /**
+     * As functions cujo evento NÃO carrega escritório — agendada, fila, HTTP, Storage. Para elas o portão
+     * não serve (falha fechado), e quem responde é o laço por escritório.
+     */
+    unscoped: TriggerDeclaration[];
     /** Os `defineString` que ela declara. O `firebase-functions` os valida GLOBALMENTE (ver abaixo). */
     parameters: BackendParameter[];
     /** As dependências npm que ela declara no `package.json` do próprio diretório. */
     dependencies: Record<string, string>;
+    /**
+     * Quem cada function COMUM serve, de `microteia.serves` no `package.json` do diretório.
+     *
+     * É a declaração que tira `functions/` da invisibilidade. A function de extensão tem dono pelo LUGAR
+     * do arquivo; a comum não tem nenhum — nenhuma extensão pode reivindicá-la —, e por isso ela ficava
+     * fora do mecanismo de retirada por inteiro: nunca entrava no registro de aplicadas, nunca era
+     * classificada como órfã, nunca era relatada, e o `--prune` não a alcançava. Ficava no ar para sempre,
+     * com todas as extensões que ela servia desinstaladas.
+     */
+    serves: Record<string, string[]>;
 }
 /**
  * Os nomes que um módulo de entrada exporta. Cobre as duas formas que se escreve de fato: o
@@ -55,12 +81,28 @@ export declare const findFunctionSources: (root: string) => Promise<FunctionSour
  * `shared` e `owned` respondem a perguntas diferentes, e é por isso que são duas listas: a comum sobe
  * no `deploy`, sempre; a de extensão sobe pelo provisionamento, e só onde a extensão está instalada.
  */
+/** Uma function comum e as extensões que ela declara servir. */
+export interface SharedRequirement {
+    name: string;
+    serves: string[];
+}
 export interface OfficeFunctions {
     sources: FunctionSource[];
     /** Todos os nomes, na ordem em que as origens são lidas. */
     all: string[];
-    /** As de `functions/` — sem dono, e por isso deployadas sempre. */
+    /** As de `functions/`, declarem ou não a quem servem. */
     shared: string[];
+    /**
+     * As comuns que DECLARAM quem servem. Elas entram no mecanismo de retirada: sobem pelo
+     * provisionamento enquanto alguma das extensões servidas estiver instalada, e viram órfãs quando
+     * nenhuma estiver.
+     */
+    served: SharedRequirement[];
+    /**
+     * As comuns SEM declaração. Sobem no `deploy`, sempre, e nada as retira — é o comportamento anterior,
+     * mantido para não quebrar instalação nenhuma, e relatado para não seguir invisível.
+     */
+    unserved: string[];
     callables: string[];
     parameters: BackendParameter[];
 }
@@ -76,6 +118,14 @@ export declare const readOfficeFunctions: (root: string) => Promise<OfficeFuncti
  * 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 declare const servesProblems: (sources: FunctionSource[]) => string[];
 export declare const functionProblems: (sources: FunctionSource[], kernelFunctions: string[]) => string[];
 /**
  * Duas declarações da MESMA dependência com faixas diferentes, entre diretórios do escritório.