@microteia/console 2.10.0 → 2.18.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,55 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [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.18.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,79 @@
+/**
+ * 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;

package/lib/console/appliedFunctions.js

@@ -0,0 +1,88 @@
+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})`;

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.

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, ungatedTriggerProblems, unguardedCallableProblems, unguardedSharedProblems, unscopedDeclarations, unscopedTriggerProblems, } 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,13 @@ export const functionProblems = (sources, kernelFunctions) => {
             }
         }
     }
+    problems.push(...servesProblems(sources));
+    // O portão de instalação entra aqui, e não numa verificação à parte, porque o momento é o mesmo: é
+    // este o ponto em que a fonte do escritório passa a fazer parte do pacote que vai subir.
+    problems.push(...ungatedTriggerProblems(sources));
+    problems.push(...unscopedTriggerProblems(sources));
+    problems.push(...unguardedSharedProblems(sources));
+    problems.push(...unguardedCallableProblems(sources));
     return problems;
 };
 const barrel = (sources) => `// Generated by "microteia deploy". Do not edit.

package/lib/console/deploy.js

@@ -125,17 +125,27 @@ 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];
             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: `