@microteia/console 2.36.0 → 2.38.0

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,19 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.38.0] — 2026-11-05
+
+- feat(provision): deploys the Cloud Functions source an extension ships in its package, after the project operator approves that exact SHA-256. The Console recomputes the hash over what it writes (mismatch or a path outside the folder is refused), shows the files, the npm dependencies and the kind of each function, and asks; outside a terminal it holds the extension and prints `microteia provision --approve <id>@<hash>`. Approved source goes to `.microteia/packaged-functions/` and is read like any extension source (gate, duplicate names, dependencies); the copy to read before approving goes to `.microteia/packaged-review/` and is never mounted. A source already in the installation or the kernel wins over the packaged one.
+- feat(provision): approval belongs to the project — the hash approved on any active copy counts, and the stamp propagates it with the approver (`gcloud` account) to every copy with the same fingerprint. A held extension stays refused, so `--prune` keeps the previous version's functions running. With different versions across organizations, the newest one is deployed. `deploy` passes `--approve` through.
+
+#### [2.37.0] — 2026-11-05
+
+- feat(provision): records on each installed copy WHY an extension is still pending (`backendPending`), refused claims included — function source not found, claim refused (platform or shared name, misgated trigger), gate missing, deploy failed — with the functions involved, so the Extensions screen can say it. The stamp now writes `backendState` and clears `backendPending` in one PATCH, so the screen never shows an extension as running and as refused at once. A copy already stamped is left alone.
+
+#### [2.36.1] — 2026-11-05
+
+- fix(publish): resuming an interrupted kernel publish now takes the release out of draft (`gh release edit --draft=false`) before writing the catalog. `gh release create` with assets creates a draft, uploads, then publishes; a GitHub 502 in between left the draft, and the resume only re-uploaded the assets — so `kernel/index.json` promoted to `latest` a tarball that only the publisher could download. On a release already published the edit changes nothing.
+
 #### [2.36.0] — 2026-11-05
 
 - fix(environment): every command that acts on an installation (`readEnvironment`) refuses when the installation's `CONSOLE-VERSIONS.md` names a Console newer than the one running. An older Console rewrites `microteia.yaml` with only the sections it knows and replaces `CONSOLE-VERSIONS.md` and `MICROTEIA.md` with its own texts — nothing failed: a forgotten copy of Console 2.6.0, left in a folder of the installation, ran `unpack` there, the `login:` block disappeared and the Console history lost thirty versions without a word. No new field marks it, on purpose: an older Console would drop the field it does not know.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.36.0
+# Microteia Console 2.38.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/backendPending.d.ts

@@ -0,0 +1,36 @@
+import type { BackendPendingReason, PluginBackendRequirement } from '../kernel/backendShape.js';
+export interface PendingCause {
+    reason: BackendPendingReason;
+    functions: string[];
+}
+/** O que uma execução do `provision` sabe sobre as functions — a mesma conta que ele já faz. */
+export interface PendingInputs {
+    /**
+     * As extensões cuja fonte EMPACOTADA não subiu nesta execução: aguardando aprovação, ou recusada por
+     * não conferir. Vem antes de tudo — sem ela, a fonte "não existe" para o resto da conta, e o motivo
+     * mandaria procurar a pasta que o autor nunca precisou criar.
+     */
+    held?: ReadonlyMap<string, BackendPendingReason>;
+    /** O que existe para ser deployado: o pacote do kernel mais as fontes da instalação. */
+    deployable: ReadonlySet<string>;
+    /** Nome -> a extensão cuja reivindicação foi recusada por ele (plataforma, comum, portão trocado). */
+    refusedClaims: ReadonlyMap<string, string>;
+    /** As que estavam na fila e saíram dela por falta do portão. */
+    ungated: ReadonlySet<string>;
+    /** O que está no ar depois desta execução: aplicado antes, subido agora ou pulado por estar igual. */
+    satisfied: ReadonlySet<string>;
+}
+/**
+ * Por que ESTA extensão continua pendente, na ordem em que um autor teria de resolver.
+ *
+ * A ordem importa porque as causas se encadeiam: sem fonte não há portão a conferir, e sem portão não
+ * há deploy que possa falhar. Relatar a última em vez da primeira mandaria corrigir algo que nem chegou
+ * a ser tentado.
+ *
+ * Nulo quando nada falta — inclusive quando a extensão não exige function nenhuma: índice que não
+ * converge derruba o comando inteiro, e parâmetro vazio não impede o carimbo.
+ */
+export declare const pendingCauseOf: (claim: {
+    pluginId: string;
+    backend: PluginBackendRequirement;
+}, inputs: PendingInputs) => PendingCause | null;

package/lib/console/backendPending.js

@@ -0,0 +1,30 @@
+/**
+ * Por que ESTA extensão continua pendente, na ordem em que um autor teria de resolver.
+ *
+ * A ordem importa porque as causas se encadeiam: sem fonte não há portão a conferir, e sem portão não
+ * há deploy que possa falhar. Relatar a última em vez da primeira mandaria corrigir algo que nem chegou
+ * a ser tentado.
+ *
+ * Nulo quando nada falta — inclusive quando a extensão não exige function nenhuma: índice que não
+ * converge derruba o comando inteiro, e parâmetro vazio não impede o carimbo.
+ */
+export const pendingCauseOf = (claim, inputs) => {
+    const names = claim.backend.functions ?? [];
+    const pick = (test) => names.filter(test);
+    const held = inputs.held?.get(claim.pluginId);
+    if (held !== undefined && names.length > 0)
+        return { reason: held, functions: [...names] };
+    const missing = pick((name) => !inputs.deployable.has(name));
+    if (missing.length > 0)
+        return { reason: 'function-source-missing', functions: missing };
+    const refused = pick((name) => inputs.refusedClaims.get(name) === claim.pluginId);
+    if (refused.length > 0)
+        return { reason: 'function-claim-refused', functions: refused };
+    const ungated = pick((name) => inputs.ungated.has(name));
+    if (ungated.length > 0)
+        return { reason: 'gate-missing', functions: ungated };
+    const failed = pick((name) => !inputs.satisfied.has(name));
+    if (failed.length > 0)
+        return { reason: 'deploy-failed', functions: failed };
+    return null;
+};

package/lib/console/customFunctions.d.ts

@@ -73,6 +73,7 @@ export interface FunctionSource {
  * `export const x = onCall(...)` de quem declara no lugar, e o `export { a, b }` de quem reexporta.
  */
 export declare const exportedNames: (source: string) => string[];
+export declare const readFunctionSource: (path: string, label: string, slug: string, shared: boolean) => Promise<FunctionSource>;
 /** Onde o escritório pode ter escrito function, na ordem em que as mensagens as citam. */
 export declare const findFunctionSources: (root: string) => Promise<FunctionSource[]>;
 /**

package/lib/console/customFunctions.js

@@ -2,6 +2,7 @@ import { access, cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/pro
 import { basename, join } from 'node:path';
 import { callableFunctionNames, declaredParametersIn } from '../kernel/manifest.js';
 import { callableDeclarations, triggerDeclarations, unscopedDeclarations, } from './functionGate.js';
+import { packagedFunctionsPath, packagedLabel } from './packagedPaths.js';
 /**
  * As Cloud Functions do ESCRITÓRIO — as que ele escreve, não as do kernel.
  *
@@ -107,7 +108,7 @@ const readServes = async (path, label) => {
     }
     return serves;
 };
-const readSource = async (path, label, slug, shared) => {
+export const readFunctionSource = async (path, label, slug, shared) => {
     const entry = join(path, 'index.ts');
     if (!await exists(entry)) {
         throw new Error(`${label}/ has no index.ts.\n`
@@ -160,7 +161,7 @@ const readSource = async (path, label, slug, shared) => {
 export const findFunctionSources = async (root) => {
     const found = [];
     if (await exists(join(root, FUNCTIONS_DIR))) {
-        found.push(await readSource(join(root, FUNCTIONS_DIR), FUNCTIONS_DIR, 'shared', true));
+        found.push(await readFunctionSource(join(root, FUNCTIONS_DIR), FUNCTIONS_DIR, 'shared', true));
     }
     const extensions = join(root, EXTENSIONS_DIR);
     if (await exists(extensions)) {
@@ -170,7 +171,18 @@ export const findFunctionSources = async (root) => {
             const path = join(extensions, entry.name, FUNCTIONS_DIR);
             if (!await exists(path))
                 continue;
-            found.push(await readSource(path, `${EXTENSIONS_DIR}/${entry.name}/${FUNCTIONS_DIR}`, entry.name, false));
+            found.push(await readFunctionSource(path, `${EXTENSIONS_DIR}/${entry.name}/${FUNCTIONS_DIR}`, entry.name, false));
+        }
+    }
+    // A fonte que veio DENTRO do pacote de uma extensão, extraída pelo `provision` — só a que foi aprovada
+    // chega aqui. Entra como qualquer outra fonte de extensão: o portão, os nomes repetidos e as
+    // dependências são conferidos pelas mesmas funções, e é isso que dispensa uma segunda régua.
+    const packaged = packagedFunctionsPath(root);
+    if (await exists(packaged)) {
+        for (const entry of (await readdir(packaged, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory())
+                continue;
+            found.push(await readFunctionSource(join(packaged, entry.name), packagedLabel(entry.name), entry.name, false));
         }
     }
     return found;

package/lib/console/deploy.js

@@ -1,6 +1,7 @@
 import { writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { flagValue, hasFlag, requiredFlag } from '../shared/args.js';
+import { parseApprovals } from './packagedSources.js';
 import { run } from '../shared/run.js';
 import { blank, bullets, failure, heading, info, step, success, warn } from '../shared/ui.js';
 import { ENVIRONMENT_FILE, readEnvironment, writeEnvironment } from './environment.js';
@@ -305,6 +306,8 @@ export const deploy = async (args) => {
             refreshedStamps,
             environmentFile: file,
             environment: applied,
+            approvals: parseApprovals(flagValue(args, 'approve')),
+            interactive: process.stdin.isTTY === true,
         });
         if (provisioned.failed.length > 0) {
             failures.push(`${provisioned.failed.length} extension function(s): ${provisioned.failed.join(', ')}`);

package/lib/console/firestoreRest.d.ts

@@ -3,6 +3,12 @@ export interface FirestoreDocument {
     fields: Record<string, unknown>;
 }
 export declare const accessToken: () => Promise<string>;
+/**
+ * A conta do `gcloud` que está agindo — é quem fica registrado como tendo aprovado o código de uma
+ * extensão. Vazio vira "unknown" em vez de recusa: a aprovação já aconteceu, e perdê-la por não saber
+ * dizer o nome seria pior que gravá-la sem ele.
+ */
+export declare const activeAccount: () => Promise<string>;
 /** Um valor tipado da REST virando valor de JavaScript. Timestamp vira string ISO, que é o que basta. */
 export declare const decodeValue: (value: unknown) => unknown;
 export declare const decodeFields: (fields: Record<string, unknown>) => Record<string, unknown>;
@@ -30,6 +36,8 @@ export type FirestoreTypedValue = {
     mapValue: {
         fields: Record<string, FirestoreTypedValue>;
     };
+} | {
+    nullValue: null;
 };
 export declare const asString: (value: string) => FirestoreTypedValue;
 /**
@@ -49,6 +57,8 @@ export declare const asMap: (fields: Record<string, FirestoreTypedValue>) => Fir
  * também o que permite ordenar e comparar o campo no banco. A REST exige RFC 3339 em UTC, que é
  * exatamente o que `toISOString` devolve.
  */
+/** O campo continua no documento, valendo nulo — é o que o lado do kernel lê como "nada a dizer". */
+export declare const asNull: () => FirestoreTypedValue;
 export declare const asTimestamp: (value: Date) => FirestoreTypedValue;
 /**
  * Grava UM campo de mapa, com `updateMask` — o resto do documento não é tocado. É o que permite o

package/lib/console/firestoreRest.js

@@ -27,6 +27,20 @@ export const accessToken = async () => {
         throw new Error('gcloud returned an empty access token. Run: gcloud auth login');
     return cachedToken;
 };
+/**
+ * A conta do `gcloud` que está agindo — é quem fica registrado como tendo aprovado o código de uma
+ * extensão. Vazio vira "unknown" em vez de recusa: a aprovação já aconteceu, e perdê-la por não saber
+ * dizer o nome seria pior que gravá-la sem ele.
+ */
+export const activeAccount = async () => {
+    try {
+        const account = (await captureOrThrow(GCLOUD_BIN, ['config', 'get-value', 'account'])).trim();
+        return account === '' || account === '(unset)' ? 'unknown' : account;
+    }
+    catch {
+        return 'unknown';
+    }
+};
 /**
  * `X-Goog-User-Project` diz de qual projeto é a cota. Sem ele, uma credencial de usuário é recusada
  * com uma mensagem sobre "quota project" que não menciona o que fazer.
@@ -125,6 +139,8 @@ export const asMap = (fields) => ({ mapValue: { fields } });
  * também o que permite ordenar e comparar o campo no banco. A REST exige RFC 3339 em UTC, que é
  * exatamente o que `toISOString` devolve.
  */
+/** O campo continua no documento, valendo nulo — é o que o lado do kernel lê como "nada a dizer". */
+export const asNull = () => ({ nullValue: null });
 export const asTimestamp = (value) => ({ timestampValue: value.toISOString() });
 /**
  * Grava UM campo de mapa, com `updateMask` — o resto do documento não é tocado. É o que permite o

package/lib/console/packagedApproval.d.ts

@@ -0,0 +1,27 @@
+import type { PackagedClaim } from './packagedSources.js';
+export type HeldReason = 'awaiting-approval' | 'source-invalid';
+export interface PackagedSettlement {
+    /** As que não sobem nesta execução, e por quê — vira o motivo que a tela da extensão mostra. */
+    held: Map<string, HeldReason>;
+    /** Quem aprovou, para as aprovadas AGORA. As já aprovadas antes guardam o aprovador que tinham. */
+    approvedNow: Map<string, string>;
+    /** Quantas fontes foram extraídas para `.microteia/packaged-functions/`. */
+    extracted: number;
+}
+/**
+ * Decide, extrai e — quando ninguém respondeu antes — pergunta. Só a fonte APROVADA fica no disco
+ * quando esta função devolve, e é por isso que o resto do `provision` pode lê-la como qualquer outra:
+ * `findFunctionSources` só encontra o que passou por aqui.
+ *
+ * Fora de um terminal não há pergunta: a extensão fica pendente e o comando diz a linha exata que a
+ * aprova. Um `--yes` genérico foi recusado de propósito — ele aprovaria também a versão que chegar
+ * amanhã, sem ninguém ter lido.
+ */
+export declare const settlePackagedSources: (input: {
+    root: string;
+    projectId: string;
+    claims: PackagedClaim[];
+    provided: ReadonlySet<string>;
+    flags: ReadonlyMap<string, string>;
+    interactive: boolean;
+}) => Promise<PackagedSettlement>;

package/lib/console/packagedApproval.js

@@ -0,0 +1,109 @@
+import { relative } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { blank, bullets, failure, info, success, warn } from '../shared/ui.js';
+import { readFunctionSource } from './customFunctions.js';
+import { activeAccount } from './firestoreRest.js';
+import { packagedLabel, packagedSlug } from './packagedPaths.js';
+import { approvalFlag, declaredDependencies, decideWithoutAsking, writePackagedSource, } from './packagedSources.js';
+const kb = (text) => `${Math.max(1, Math.round(Buffer.byteLength(text, 'utf8') / 1024))} KB`;
+/**
+ * O que quem aprova precisa ver ANTES de dizer sim — e é a lista inteira, não um resumo: o que vai ao
+ * ar, com que dependência, e de que tipo é cada function. O tipo importa porque muda o alcance: uma
+ * callable responde a quem a chama; um gatilho age sozinho sobre os dados; uma agendada age sobre todos
+ * os escritórios do projeto.
+ */
+const describe = async (root, projectId, claim, path) => {
+    const slug = packagedSlug(claim.pluginId);
+    const source = await readFunctionSource(path, packagedLabel(slug), slug, false);
+    const kindOf = (name) => {
+        if (source.callables.includes(name))
+            return 'callable — answers whoever calls it';
+        const trigger = source.triggers.find((entry) => entry.name === name);
+        if (trigger !== undefined)
+            return `${trigger.trigger} — acts on its own when data changes`;
+        const unscoped = source.unscoped.find((entry) => entry.name === name);
+        if (unscoped !== undefined)
+            return `${unscoped.trigger} — acts on its own, for every organization`;
+        return 'not exported by its index.ts';
+    };
+    const dependencies = Object.entries(declaredDependencies(claim.source));
+    blank();
+    warn(`${claim.name} ${claim.version} (${claim.pluginId}) brings the source of its own Cloud Functions.`);
+    info(`  They run on the server with full access to every organization in ${projectId}.`);
+    info(`  sha-256: ${claim.source.hash}`);
+    info(`  read it in: ${relative(root, path)}/`);
+    info('  files:');
+    bullets(Object.keys(claim.source.files).sort().map((file) => `${file} (${kb(claim.source.files[file] ?? '')})`));
+    info('  npm dependencies it adds:');
+    bullets(dependencies.length === 0 ? ['none beyond the platform\'s own'] : dependencies.map(([name, range]) => `${name} ${range}`));
+    info('  functions:');
+    bullets(claim.functions.map((name) => `${name} — ${kindOf(name)}`));
+};
+const ask = async (question) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return /^(y|yes)$/i.test((await rl.question(question)).trim());
+    }
+    finally {
+        rl.close();
+    }
+};
+/**
+ * Decide, extrai e — quando ninguém respondeu antes — pergunta. Só a fonte APROVADA fica no disco
+ * quando esta função devolve, e é por isso que o resto do `provision` pode lê-la como qualquer outra:
+ * `findFunctionSources` só encontra o que passou por aqui.
+ *
+ * Fora de um terminal não há pergunta: a extensão fica pendente e o comando diz a linha exata que a
+ * aprova. Um `--yes` genérico foi recusado de propósito — ele aprovaria também a versão que chegar
+ * amanhã, sem ninguém ter lido.
+ */
+export const settlePackagedSources = async (input) => {
+    const settlement = { held: new Map(), approvedNow: new Map(), extracted: 0 };
+    let account;
+    const approver = async () => {
+        account ??= await activeAccount();
+        return account;
+    };
+    for (const claim of input.claims) {
+        const decision = decideWithoutAsking(claim, input.provided, input.flags);
+        if (decision?.kind === 'provided') {
+            info(`  ${claim.name}: using the source in this installation, not the copy in its package`);
+            continue;
+        }
+        if (decision?.kind === 'invalid') {
+            failure(`${claim.name}: the server code in its package cannot be used —`);
+            bullets(decision.problems);
+            info('  Install the extension again from a file its author built.');
+            settlement.held.set(claim.pluginId, 'source-invalid');
+            continue;
+        }
+        if (decision?.kind === 'approved') {
+            await writePackagedSource(input.root, claim);
+            settlement.extracted += 1;
+            if (decision.how === 'flag') {
+                settlement.approvedNow.set(claim.pluginId, await approver());
+                success(`${claim.name}: server code approved by --approve`);
+            }
+            continue;
+        }
+        if (decision?.kind === 'held') {
+            warn(`${claim.name}: the hash given to --approve is not the one in its package.`);
+            info(`  the package carries ${claim.source.hash} — read it before approving that one.`);
+            settlement.held.set(claim.pluginId, 'awaiting-approval');
+            continue;
+        }
+        const review = await writePackagedSource(input.root, claim, 'review');
+        await describe(input.root, input.projectId, claim, review);
+        if (input.interactive && await ask(`Approve this exact code for ${input.projectId}? [y/N] `)) {
+            await writePackagedSource(input.root, claim);
+            settlement.extracted += 1;
+            settlement.approvedNow.set(claim.pluginId, await approver());
+            success(`${claim.name}: server code approved`);
+            continue;
+        }
+        settlement.held.set(claim.pluginId, 'awaiting-approval');
+        info('  Not approved — the extension stays pending. To approve it without a prompt:');
+        bullets([`microteia provision ${approvalFlag(claim.pluginId, claim.source.hash)}`]);
+    }
+    return settlement;
+};

package/lib/console/packagedPaths.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Onde o Console extrai a fonte das Cloud Functions que veio DENTRO do pacote de uma extensão.
+ *
+ * Fica em `.microteia/` de propósito, e é a exceção que confirma a regra daquele diretório: nada ali é
+ * digitado por ninguém. É derivado do banco — o pacote instalado está em `installed_extensions` —, então
+ * o `unpack` apagar tudo não perde nada: o próximo `provision` extrai de novo. O que o autor escreve
+ * continua em `extensions/<pasta>/functions/`, e o Console nunca escreve lá.
+ */
+export declare const PACKAGED_FUNCTIONS_DIR = "packaged-functions";
+export declare const packagedFunctionsPath: (root: string) => string;
+/**
+ * Onde fica a cópia para LEITURA da fonte que ainda não foi aprovada. Separada de propósito: o que está
+ * em `packaged-functions/` é montado e sobe; o que está aqui só é lido por quem vai decidir. Uma pasta
+ * só obrigaria a apagar o código justamente quando alguém precisa lê-lo para aprovar com `--approve`.
+ */
+export declare const PACKAGED_REVIEW_DIR = "packaged-review";
+export declare const packagedReviewPath: (root: string) => string;
+export declare const packagedLabel: (slug: string) => string;
+/**
+ * O diretório da extensão. O prefixo impede colisão com `extensions/<pasta>`, que vai para o mesmo
+ * `custom/src/`: as duas origens viram irmãs ali dentro.
+ */
+export declare const packagedSlug: (pluginId: string) => string;

package/lib/console/packagedPaths.js

@@ -0,0 +1,25 @@
+import { join } from 'node:path';
+import { WORKSPACE_DIR } from './workspace.js';
+/**
+ * Onde o Console extrai a fonte das Cloud Functions que veio DENTRO do pacote de uma extensão.
+ *
+ * Fica em `.microteia/` de propósito, e é a exceção que confirma a regra daquele diretório: nada ali é
+ * digitado por ninguém. É derivado do banco — o pacote instalado está em `installed_extensions` —, então
+ * o `unpack` apagar tudo não perde nada: o próximo `provision` extrai de novo. O que o autor escreve
+ * continua em `extensions/<pasta>/functions/`, e o Console nunca escreve lá.
+ */
+export const PACKAGED_FUNCTIONS_DIR = 'packaged-functions';
+export const packagedFunctionsPath = (root) => join(root, WORKSPACE_DIR, PACKAGED_FUNCTIONS_DIR);
+/**
+ * Onde fica a cópia para LEITURA da fonte que ainda não foi aprovada. Separada de propósito: o que está
+ * em `packaged-functions/` é montado e sobe; o que está aqui só é lido por quem vai decidir. Uma pasta
+ * só obrigaria a apagar o código justamente quando alguém precisa lê-lo para aprovar com `--approve`.
+ */
+export const PACKAGED_REVIEW_DIR = 'packaged-review';
+export const packagedReviewPath = (root) => join(root, WORKSPACE_DIR, PACKAGED_REVIEW_DIR);
+export const packagedLabel = (slug) => `${WORKSPACE_DIR}/${PACKAGED_FUNCTIONS_DIR}/${slug}`;
+/**
+ * O diretório da extensão. O prefixo impede colisão com `extensions/<pasta>`, que vai para o mesmo
+ * `custom/src/`: as duas origens viram irmãs ali dentro.
+ */
+export const packagedSlug = (pluginId) => `package-${pluginId.replace(/[^a-zA-Z0-9]+/g, '-')}`;

package/lib/console/packagedSources.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A fonte das Cloud Functions que viaja no pacote — redeclarada do lado do Console pelo mesmo motivo de
+ * `backendShape.ts`: ele é publicado sem o `src/`. `packagedSources.test.ts` confere a serialização e a
+ * regra de caminho contra o kernel; separadas em silêncio, o hash que o build grava nunca conferiria
+ * aqui, e toda extensão com fonte seria recusada como adulterada.
+ */
+export interface PackagedSource {
+    files: Record<string, string>;
+    hash: string;
+}
+export declare const canonicalSource: (files: Record<string, string>) => string;
+export declare const hashSource: (files: Record<string, string>) => string;
+export declare const isSourcePath: (path: string) => boolean;
+/**
+ * A fonte como ela está gravada no pacote instalado. Leniente na LEITURA — a forma é cobrada por
+ * `sourceProblems` —, porque o que veio do banco é dado, e um dado torto tem de virar recusa explicada,
+ * não exceção.
+ */
+export declare const packagedSourceOf: (pkg: unknown) => PackagedSource | undefined;
+/**
+ * O que impede a fonte de ir ao disco. A conferência é feita AQUI, e não só na importação: o pacote
+ * chega ao Console pelo banco, e quem tem `extensions.manage` grava o documento instalado diretamente.
+ * O hash é recalculado sobre o conteúdo que vai ser gravado — é ele que se aprova.
+ */
+export declare const sourceProblems: (source: PackagedSource) => string[];
+/** `--approve id@hash,id@hash`. O hash INTEIRO: aprovar por prefixo é aprovar o que não se leu. */
+export declare const parseApprovals: (value: string | undefined) => Map<string, string>;
+export declare const approvalFlag: (pluginId: string, hash: string) => string;
+/** Uma extensão cuja fonte veio no pacote, com o que o projeto já aprovou dela. */
+export interface PackagedClaim {
+    pluginId: string;
+    name: string;
+    version: string;
+    functions: string[];
+    source: PackagedSource;
+    /** Os hashes aprovados em QUALQUER cópia instalada no projeto — a aprovação é do projeto. */
+    approvedHashes: ReadonlySet<string>;
+}
+export type PackagedDecision = {
+    kind: 'provided';
+} | {
+    kind: 'invalid';
+    problems: string[];
+} | {
+    kind: 'held';
+    flagMismatch: boolean;
+} | {
+    kind: 'approved';
+    how: 'recorded' | 'flag' | 'prompt';
+};
+/**
+ * A decisão que não depende de perguntar a ninguém. `null` é "pergunte": só então a revisão humana
+ * entra, e só para o que nenhuma outra resposta cobre.
+ *
+ * `provided` vem antes de tudo: se o pacote do kernel ou a instalação (`extensions/<pasta>/functions/`)
+ * já exporta um nome que a extensão reivindica, a fonte local vale — é onde o autor desenvolve, e é o
+ * caso da instalação que é a casa da fonte. As duas juntas seriam o mesmo nome exportado duas vezes,
+ * que a montagem recusa.
+ */
+export declare const decideWithoutAsking: (claim: PackagedClaim, provided: ReadonlySet<string>, flags: ReadonlyMap<string, string>) => PackagedDecision | null;
+/**
+ * Grava a fonte no diretório da extensão, dentro de `.microteia/packaged-functions/`.
+ *
+ * Cada caminho é conferido DE NOVO contra o diretório de destino depois de resolvido. `sourceProblems`
+ * já recusou `..` e caminho absoluto, mas é esta a linha que escreve no disco, e a regra dela não pode
+ * depender de alguém lembrar de chamar a outra antes.
+ */
+export declare const writePackagedSource: (root: string, claim: PackagedClaim, purpose?: "deploy" | "review") => Promise<string>;
+/** As duas pastas recomeçam a cada execução: o que vale é o que está instalado AGORA. */
+export declare const clearPackagedSources: (root: string) => Promise<void>;
+/** As dependências npm que a fonte declara — o que a aprovação precisa mostrar além do código. */
+export declare const declaredDependencies: (source: PackagedSource) => Record<string, string>;

package/lib/console/packagedSources.js

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { packagedFunctionsPath, packagedReviewPath, packagedSlug } from './packagedPaths.js';
+const SEPARATOR = '\u0000';
+export const canonicalSource = (files) => Object.keys(files)
+    .sort()
+    .map((path) => `${path}${SEPARATOR}${files[path]}`)
+    .join(SEPARATOR);
+export const hashSource = (files) => createHash('sha256').update(canonicalSource(files), 'utf8').digest('hex');
+const TEST_FILE = /\.(test|spec)\.ts$/;
+export const isSourcePath = (path) => {
+    if (path === '' || path.startsWith('/') || path.includes('\\'))
+        return false;
+    const segments = path.split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..'))
+        return false;
+    if (segments.some((segment) => segment.startsWith('.') || segment === 'node_modules' || segment === '__tests__')) {
+        return false;
+    }
+    const name = segments.at(-1) ?? '';
+    if (TEST_FILE.test(name))
+        return false;
+    return name.endsWith('.ts') || name.endsWith('.json');
+};
+/**
+ * A fonte como ela está gravada no pacote instalado. Leniente na LEITURA — a forma é cobrada por
+ * `sourceProblems` —, porque o que veio do banco é dado, e um dado torto tem de virar recusa explicada,
+ * não exceção.
+ */
+export const packagedSourceOf = (pkg) => {
+    const raw = pkg?.backendSource;
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const { files, hash } = raw;
+    const entries = typeof files === 'object' && files !== null
+        ? Object.entries(files)
+            .filter((entry) => typeof entry[1] === 'string')
+        : [];
+    return { files: Object.fromEntries(entries), hash: typeof hash === 'string' ? hash : '' };
+};
+/**
+ * O que impede a fonte de ir ao disco. A conferência é feita AQUI, e não só na importação: o pacote
+ * chega ao Console pelo banco, e quem tem `extensions.manage` grava o documento instalado diretamente.
+ * O hash é recalculado sobre o conteúdo que vai ser gravado — é ele que se aprova.
+ */
+export const sourceProblems = (source) => {
+    const problems = [];
+    const bad = Object.keys(source.files).filter((path) => !isSourcePath(path));
+    if (bad.length > 0)
+        problems.push(`it names files that cannot be written: ${bad.join(', ')}`);
+    if (source.files['index.ts'] === undefined)
+        problems.push('it has no index.ts');
+    if (hashSource(source.files) !== source.hash) {
+        problems.push('its checksum does not match its content — it was changed after it was built');
+    }
+    return problems;
+};
+/** `--approve id@hash,id@hash`. O hash INTEIRO: aprovar por prefixo é aprovar o que não se leu. */
+export const parseApprovals = (value) => {
+    const approvals = new Map();
+    for (const part of (value ?? '').split(',').map((item) => item.trim()).filter(Boolean)) {
+        const at = part.lastIndexOf('@');
+        if (at <= 0 || at === part.length - 1) {
+            throw new Error(`--approve takes <extension id>@<sha-256>, and "${part}" is not that.`);
+        }
+        approvals.set(part.slice(0, at), part.slice(at + 1));
+    }
+    return approvals;
+};
+export const approvalFlag = (pluginId, hash) => `--approve ${pluginId}@${hash}`;
+/**
+ * A decisão que não depende de perguntar a ninguém. `null` é "pergunte": só então a revisão humana
+ * entra, e só para o que nenhuma outra resposta cobre.
+ *
+ * `provided` vem antes de tudo: se o pacote do kernel ou a instalação (`extensions/<pasta>/functions/`)
+ * já exporta um nome que a extensão reivindica, a fonte local vale — é onde o autor desenvolve, e é o
+ * caso da instalação que é a casa da fonte. As duas juntas seriam o mesmo nome exportado duas vezes,
+ * que a montagem recusa.
+ */
+export const decideWithoutAsking = (claim, provided, flags) => {
+    if (claim.functions.some((name) => provided.has(name)))
+        return { kind: 'provided' };
+    const problems = sourceProblems(claim.source);
+    if (problems.length > 0)
+        return { kind: 'invalid', problems };
+    if (claim.approvedHashes.has(claim.source.hash))
+        return { kind: 'approved', how: 'recorded' };
+    const flagged = flags.get(claim.pluginId);
+    if (flagged === claim.source.hash)
+        return { kind: 'approved', how: 'flag' };
+    if (flagged !== undefined)
+        return { kind: 'held', flagMismatch: true };
+    return null;
+};
+/**
+ * Grava a fonte no diretório da extensão, dentro de `.microteia/packaged-functions/`.
+ *
+ * Cada caminho é conferido DE NOVO contra o diretório de destino depois de resolvido. `sourceProblems`
+ * já recusou `..` e caminho absoluto, mas é esta a linha que escreve no disco, e a regra dela não pode
+ * depender de alguém lembrar de chamar a outra antes.
+ */
+export const writePackagedSource = async (root, claim, purpose = 'deploy') => {
+    const base = purpose === 'deploy' ? packagedFunctionsPath(root) : packagedReviewPath(root);
+    const target = join(base, packagedSlug(claim.pluginId));
+    await rm(target, { recursive: true, force: true });
+    for (const [path, content] of Object.entries(claim.source.files)) {
+        const file = resolve(target, path);
+        if (!file.startsWith(`${resolve(target)}${sep}`)) {
+            throw new Error(`${claim.name}: refusing to write "${path}" outside its folder.`);
+        }
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, content);
+    }
+    return target;
+};
+/** As duas pastas recomeçam a cada execução: o que vale é o que está instalado AGORA. */
+export const clearPackagedSources = async (root) => {
+    await rm(packagedFunctionsPath(root), { recursive: true, force: true });
+    await rm(packagedReviewPath(root), { recursive: true, force: true });
+};
+/** As dependências npm que a fonte declara — o que a aprovação precisa mostrar além do código. */
+export const declaredDependencies = (source) => {
+    const manifest = source.files['package.json'];
+    if (manifest === undefined)
+        return {};
+    try {
+        const parsed = JSON.parse(manifest);
+        return Object.fromEntries(Object.entries(parsed.dependencies ?? {})
+            .filter((entry) => typeof entry[1] === 'string'));
+    }
+    catch {
+        return {};
+    }
+};

package/lib/console/provision.d.ts

@@ -2,11 +2,17 @@ import type { ParsedArgs } from '../shared/args.js';
 import type { KernelManifest } from '../kernel/manifest.js';
 import type { BackendClaim } from '../kernel/backendShape.js';
 import type { Environment } from './environment.js';
+import type { PackagedSource } from './packagedSources.js';
 /** Uma exigência, o escritório que a instalou e o documento que carrega o estado dela. */
 export interface InstalledClaim extends BackendClaim {
     tenantId: string;
     documentPath: string;
     applied: boolean;
+    /** A fonte das functions que veio no pacote — ver `PackagedSource`. */
+    source?: PackagedSource;
+    /** O hash aprovado nesta cópia, e por quem. A aprovação é do projeto: vale a de qualquer cópia. */
+    approvedHash?: string;
+    approvedBy?: string;
 }
 /**
  * A varredura inteira, e não só o que ela achou.
@@ -62,6 +68,10 @@ export interface ProvisionOptions {
     refreshedStamps?: Map<string, string>;
     environmentFile: string;
     environment: Environment;
+    /** `--approve id@hash`: aprovação da fonte empacotada sem pergunta. Ver `settlePackagedSources`. */
+    approvals?: ReadonlyMap<string, string>;
+    /** Há um terminal para perguntar. Sem ele, o que não foi aprovado fica pendente. */
+    interactive?: boolean;
 }
 export interface ProvisionOutcome {
     deployed: string[];

package/lib/console/provision.js

@@ -14,7 +14,10 @@ import { deployFunctionsThatChanged } from './functionsUpToDate.js';
 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 { asArray, asMap, asNull, asString, asTimestamp, patchFields, patchMapField } from './firestoreRest.js';
+import { pendingCauseOf } from './backendPending.js';
+import { settlePackagedSources } from './packagedApproval.js';
+import { clearPackagedSources, packagedSourceOf, parseApprovals } from './packagedSources.js';
 import { writeBackendResidue } from './backendResidue.js';
 import { listTenants, readInstalledExtensions } from './installedExtensions.js';
 import { gatherCustomFunctions, readOfficeFunctions } from './customFunctions.js';
@@ -42,6 +45,7 @@ export const surveyInstallations = async (projectId) => {
             if (!hasBackendRequirement(backend))
                 continue;
             const state = extension.data.backendState;
+            const source = packagedSourceOf(extension.data.package);
             claims.push({
                 tenantId: extension.tenantId,
                 documentPath: extension.documentPath,
@@ -49,17 +53,32 @@ export const surveyInstallations = async (projectId) => {
                 name: extension.name,
                 version: extension.version,
                 backend: backend,
-                applied: state?.fingerprint === backendFingerprint(backend),
+                applied: state?.fingerprint === backendFingerprint(backend, source?.hash),
+                ...(source !== undefined ? { source } : {}),
+                ...(typeof state?.approvedHash === 'string' ? { approvedHash: state.approvedHash } : {}),
+                ...(typeof state?.approvedBy === 'string' ? { approvedBy: state.approvedBy } : {}),
             });
         }
     }
     return {
         tenants: tenants.length,
         extensions,
-        claims: claims.sort((a, b) => (a.pluginId < b.pluginId ? -1 : a.pluginId > b.pluginId ? 1 : 0)),
+        // A versão mais nova primeiro, dentro de cada extensão: é ela que `uniqueByPlugin` escolhe quando
+        // dois escritórios do projeto têm versões diferentes — e a function é uma só, do projeto.
+        claims: claims.sort((a, b) => (a.pluginId < b.pluginId ? -1 : a.pluginId > b.pluginId ? 1 : compareVersions(b.version, a.version))),
         installedIds,
     };
 };
+const compareVersions = (left, right) => {
+    const parts = (value) => value.split(/[.+-]/).slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+    const [a, b] = [parts(left), parts(right)];
+    for (let index = 0; index < 3; index += 1) {
+        const difference = (a.at(index) ?? 0) - (b.at(index) ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+};
 const uniqueByPlugin = (claims) => {
     const seen = new Set();
     return claims.filter((claim) => {
@@ -87,11 +106,30 @@ export const provisionBackend = async (options) => {
      * pacote (nem poderia: o kernel não sabe o que o escritório vai escrever), e a extensão inteira era
      * rejeitada com "this kernel package does not contain".
      */
-    const office = await readOfficeFunctions(root);
-    const deployable = [...manifest.functions, ...office.all];
     const survey = await surveyInstallations(projectId);
     const claims = survey.claims;
-    const missing = functionClaimProblems(claims, deployable);
+    /**
+     * A fonte que veio NO PACOTE é decidida antes de qualquer conta: o que for aprovado é extraído para
+     * `.microteia/packaged-functions/` e passa a ser lido como qualquer fonte da instalação. A leitura
+     * local vem antes porque é ela que decide a precedência — o que a instalação já escreve vale mais que
+     * a cópia empacotada.
+     */
+    await clearPackagedSources(root);
+    const local = await readOfficeFunctions(root);
+    const settlement = await settlePackagedSources({
+        root,
+        projectId,
+        claims: packagedClaimsOf(claims),
+        provided: new Set([...manifest.functions, ...local.all]),
+        flags: options.approvals ?? new Map(),
+        interactive: options.interactive === true,
+    });
+    const office = settlement.extracted > 0 ? await readOfficeFunctions(root) : local;
+    const deployable = [...manifest.functions, ...office.all];
+    // A retida não entra em "nowhere to be found": a fonte dela existe, só não foi aprovada — e a
+    // explicação certa já foi dada acima. Ela continua RECUSADA (logo abaixo), e é isso que protege do
+    // `--prune` a function de uma versão anterior que ainda está no ar.
+    const missing = functionClaimProblems(claims.filter((claim) => !settlement.held.has(claim.pluginId)), 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.
@@ -195,7 +233,24 @@ export const provisionBackend = async (options) => {
         for (const entry of misgated)
             rejected.add(entry.owner);
     }
+    for (const pluginId of settlement.held.keys())
+        rejected.add(pluginId);
     const valid = uniqueByPlugin(claims.filter((claim) => !rejected.has(claim.pluginId)));
+    /**
+     * Qual nome derrubou qual reivindicação — é o que vai para a tela da extensão no fim. As mensagens
+     * acima já dizem isto em prosa; o mapa existe porque a tela é lida por quem não tem o terminal.
+     */
+    const refusedClaims = new Map();
+    const baselineNames = new Set(manifest.baselineFunctions ?? []);
+    const sharedNames = new Set(office.shared);
+    for (const claim of claims) {
+        for (const name of claim.backend.functions ?? []) {
+            if (baselineNames.has(name) || sharedNames.has(name))
+                refusedClaims.set(name, claim.pluginId);
+        }
+    }
+    for (const entry of misgated)
+        refusedClaims.set(entry.name, entry.owner);
     /**
      * 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
@@ -450,14 +505,30 @@ export const provisionBackend = async (options) => {
     // o mesmo que estar satisfeito. Deixá-lo de fora manteria a extensão "pendente" para sempre numa
     // instalação em que não falta nada.
     const deployedNow = new Set([...appliedNames, ...outcome.deployed, ...skippedNow]);
-    for (const claim of valid) {
-        const satisfied = (claim.backend.functions ?? []).every((name) => deployedNow.has(name));
-        if (satisfied) {
-            await stampApplied(projectId, claims, claim);
+    const validIds = new Set(valid.map((claim) => claim.pluginId));
+    const pendingInputs = {
+        held: settlement.held,
+        deployable: new Set(deployable),
+        refusedClaims,
+        ungated: new Set(refused),
+        satisfied: deployedNow,
+    };
+    // As RECUSADAS entram aqui também: nunca foram carimbadas, e eram justamente as que a tela mandava
+    // "rodar o provision" sem dizer que ele já tinha rodado e recusado.
+    for (const claim of uniqueByPlugin(claims)) {
+        const isValid = validIds.has(claim.pluginId);
+        // A regra do carimbo é a de sempre — tudo o que ela pede está no ar —, e vem ANTES do motivo: uma
+        // function que já estava aplicada continua satisfazendo a extensão mesmo que o portão dela tenha
+        // saído da fila nesta execução.
+        if (isValid && (claim.backend.functions ?? []).every((name) => deployedNow.has(name))) {
+            await stampApplied(projectId, claims, claim, settlement.approvedNow.get(claim.pluginId));
+            continue;
         }
-        else {
+        if (isValid)
             outcome.pending.push(claim);
-        }
+        const cause = pendingCauseOf(claim, pendingInputs);
+        if (cause !== null)
+            await recordPending(projectId, claims, claim, cause);
     }
     /**
      * O que o PROJETO roda, cruzado com o que esta instalação consegue justificar.
@@ -609,19 +680,76 @@ const checkNewCallables = async (known, deployed, projectId, region) => {
  * existe, existe para todo escritório que o instalou, e não só para aquele cuja cópia foi lida por
  * último.
  */
-const stampApplied = async (projectId, all, claim) => {
-    const fingerprint = backendFingerprint(claim.backend);
+const stampApplied = async (projectId, all, claim, approvedNowBy) => {
+    const fingerprint = claimFingerprint(claim);
     const appliedAt = new Date();
+    /**
+     * A aprovação vai junto do carimbo quando a fonte veio no pacote. Aprovada agora, o aprovador é quem
+     * rodou o comando; aprovada antes, é quem a aprovou numa das cópias — e é isso que a PROPAGA para a
+     * cópia nova de um escritório que reinstalou, sem perguntar de novo pelo código que já roda.
+     */
+    const hash = claim.source?.hash;
+    const approval = hash === undefined
+        ? {}
+        : {
+            approvedHash: asString(hash),
+            approvedBy: asString(approvedNowBy
+                ?? all.find((entry) => entry.pluginId === claim.pluginId && entry.approvedHash === hash)?.approvedBy
+                ?? 'unknown'),
+            approvedAt: asTimestamp(appliedAt),
+        };
     for (const copy of all.filter((entry) => entry.pluginId === claim.pluginId)) {
-        if (backendFingerprint(copy.backend) !== fingerprint)
+        if (claimFingerprint(copy) !== fingerprint)
             continue;
-        await patchMapField(projectId, copy.documentPath, 'backendState', {
-            fingerprint: asString(fingerprint),
-            appliedAt: asTimestamp(appliedAt),
+        // O motivo de uma recusa anterior sai na MESMA escrita: duas escritas abririam uma janela em que a
+        // tela mostra a extensão no ar e, ao mesmo tempo, por que ela não estava.
+        await patchFields(projectId, copy.documentPath, {
+            backendState: asMap({
+                fingerprint: asString(fingerprint),
+                appliedAt: asTimestamp(appliedAt),
+                ...approval,
+            }),
+            backendPending: asNull(),
         });
     }
     success(`${claim.name} is ready in ${projectId}`);
 };
+/** O fingerprint que a cópia exige — o mesmo que a tela calcula, com o hash da fonte quando ela existe. */
+const claimFingerprint = (claim) => backendFingerprint(claim.backend, claim.source?.hash);
+/**
+ * As extensões cuja fonte veio no pacote, uma por id — a escolhida por `uniqueByPlugin`, a versão mais
+ * nova —, com todos os hashes que QUALQUER cópia do projeto já aprovou.
+ */
+const packagedClaimsOf = (claims) => uniqueByPlugin(claims).flatMap((claim) => (claim.source === undefined ? [] : [{
+        pluginId: claim.pluginId,
+        name: claim.name,
+        version: claim.version,
+        functions: claim.backend.functions ?? [],
+        source: claim.source,
+        approvedHashes: new Set(claims
+            .filter((entry) => entry.pluginId === claim.pluginId && entry.approvedHash !== undefined)
+            .map((entry) => entry.approvedHash)),
+    }]));
+/**
+ * Grava na instalação POR QUE ela continua pendente — o que até aqui só o terminal sabia.
+ *
+ * Vai para toda cópia daquela extensão com a mesma exigência, pelo mesmo motivo do carimbo: a recusa é
+ * do projeto. A cópia já carimbada fica de fora: ela está no ar, e um motivo nela só confundiria.
+ */
+const recordPending = async (projectId, all, claim, cause) => {
+    const fingerprint = claimFingerprint(claim);
+    const recordedAt = new Date();
+    for (const copy of all.filter((entry) => entry.pluginId === claim.pluginId)) {
+        if (copy.applied || claimFingerprint(copy) !== fingerprint)
+            continue;
+        await patchMapField(projectId, copy.documentPath, 'backendPending', {
+            fingerprint: asString(fingerprint),
+            reason: asString(cause.reason),
+            functions: asArray(cause.functions.map(asString)),
+            recordedAt: asTimestamp(recordedAt),
+        });
+    }
+};
 /**
  * O que ninguém exige e mesmo assim NÃO é órfã.
  *
@@ -847,6 +975,8 @@ export const provision = async (args) => {
         all: hasFlag(args, 'all'),
         environmentFile: file,
         environment,
+        approvals: parseApprovals(flagValue(args, 'approve')),
+        interactive: process.stdin.isTTY === true,
     });
     blank();
     if (outcome.failed.length > 0) {

package/lib/kernel/backendShape.d.ts

@@ -33,7 +33,10 @@ export interface BackendClaim {
     backend: PluginBackendRequirement;
 }
 /** Cópia byte a byte de `domain/schema/plugin/backendRequirement.ts`. Ver o teste de paridade. */
-export declare const backendFingerprint: (backend?: PluginBackendRequirement) => string;
+export declare const backendFingerprint: (backend?: PluginBackendRequirement, sourceHash?: string) => string;
+/** Ver `BACKEND_PENDING_REASONS` no kernel — a paridade é cobrada por `backendShape.test.ts`. */
+export declare const BACKEND_PENDING_REASONS: readonly ["function-source-missing", "function-claim-refused", "gate-missing", "deploy-failed", "awaiting-approval", "source-invalid"];
+export type BackendPendingReason = typeof BACKEND_PENDING_REASONS[number];
 export declare const hasBackendRequirement: (backend?: PluginBackendRequirement) => boolean;
 /** Chave de identidade de um índice, para deduplicar e para casar reivindicação com a raiz. */
 export declare const indexKey: (index: FirestoreIndexSpec) => string;

package/lib/kernel/backendShape.js

@@ -4,11 +4,21 @@ const canonicalIndex = (index) => JSON.stringify([
     index.fields.map((field) => [field.fieldPath, field.order ?? '', field.arrayConfig ?? '']),
 ]);
 /** Cópia byte a byte de `domain/schema/plugin/backendRequirement.ts`. Ver o teste de paridade. */
-export const backendFingerprint = (backend) => JSON.stringify({
+export const backendFingerprint = (backend, sourceHash) => JSON.stringify({
     functions: [...(backend?.functions ?? [])].sort(),
     indexes: [...(backend?.indexes ?? [])].map(canonicalIndex).sort(),
     parameters: [...(backend?.parameters ?? [])].sort(),
+    ...(sourceHash !== undefined ? { code: sourceHash } : {}),
 });
+/** Ver `BACKEND_PENDING_REASONS` no kernel — a paridade é cobrada por `backendShape.test.ts`. */
+export const BACKEND_PENDING_REASONS = [
+    'function-source-missing',
+    'function-claim-refused',
+    'gate-missing',
+    'deploy-failed',
+    'awaiting-approval',
+    'source-invalid',
+];
 export const hasBackendRequirement = (backend) => (backend?.functions?.length ?? 0) > 0
     || (backend?.indexes?.length ?? 0) > 0
     || (backend?.parameters?.length ?? 0) > 0;

package/lib/shared/paths.d.ts

@@ -87,4 +87,4 @@ export declare const consoleRoot: string;
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export declare const CLI_VERSION = "2.36.0";
+export declare const CLI_VERSION = "2.38.0";

package/lib/shared/paths.js

@@ -94,4 +94,4 @@ export const consoleRoot = resolve(here, '..', '..');
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export const CLI_VERSION = '2.36.0';
+export const CLI_VERSION = '2.38.0';

package/lib/vendor/publish.js

@@ -247,6 +247,13 @@ const publishKernel = async (root, version, repo, dryRun) => {
                 'release', 'upload', tagOf(version), tarball, manifestPath,
                 '--repo', repo, '--clobber',
             ]);
+            /**
+             * O `gh release create` com arquivos cria o release como RASCUNHO, sobe os arquivos e só então o
+             * publica. Interrompido no meio — foi um 502 do GitHub —, sobra o rascunho, e o arquivo de um
+             * rascunho não se baixa sem credencial: retomar só subindo os arquivos gravava no catálogo um
+             * `latest` que nenhum escritório consegue instalar. Em release já publicado, isto não muda nada.
+             */
+            await run('gh', ['release', 'edit', tagOf(version), '--repo', repo, '--draft=false']);
         }
         else {
             pending(`creating ${tagOf(version)} in ${repo}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microteia/console",
-  "version": "2.36.0",
+  "version": "2.38.0",
   "description": "Install and update Microteia in a Firebase project you own.",
   "license": "UNLICENSED",
   "type": "module",