synthesisui 0.16.419 → 0.16.421

package/dist/copy/connect.pt-BR.js

@@ -120,6 +120,18 @@ register("pt-BR", {
     "the skills": "as skills",
     // ── o custo do hook ──
     "The hook resolves against the npm registry on each edit - that is the wait, not the check. Add synthesisui to your devDependencies and run this again; it switches by itself to local, several times faster.": "O hook resolve no registro do npm a cada edição - a espera é isso, não a verificação. Adicione synthesisui às suas devDependencies e rode isto de novo; ele passa a resolver local sozinho, várias vezes mais rápido.",
+    // ── até onde a garantia vai (uma vez, e de novo só quando a resposta muda) ──
+    "How far this check goes here": "Até onde esta verificação vai aqui",
+    "Every file this project writes is checked as it is written - by an edit tool or by a shell command, it makes no difference.": "Todo arquivo que este projeto escreve é verificado no momento da escrita - por uma ferramenta de edição ou por um comando de shell, dá no mesmo.",
+    "Nothing is checked automatically here yet: this project has no write check installed.": "Nada é verificado sozinho aqui ainda: este projeto não tem a verificação de escrita instalada.",
+    "What a file no longer has is measured against your last commit. A file git has never seen has no before, so nothing is reported as removed there.": "O que um arquivo deixou de ter é medido contra o seu último commit. Um arquivo que o git nunca viu não tem um antes, então nada é reportado como removido nele.",
+    "A value counts as coming from your system in two spellings: `var(--token)`, and the {n} utility names your own theme generates - `bg-primary`, `p-6`, `rounded-lg`.": "Um valor conta como vindo do seu sistema em duas grafias: `var(--token)`, e os {n} nomes de utility que o seu próprio tema gera - `bg-primary`, `p-6`, `rounded-lg`.",
+    "A value counts as coming from your system when it is written as `var(--token)`. This system declares no theme names, so a utility class is not read as a reference to it.": "Um valor conta como vindo do seu sistema quando é escrito como `var(--token)`. Este sistema não declara nomes de tema, então uma classe utility não é lida como referência a ele.",
+    "Every file in this project is checked as you write it, except {out}, which you named under `ungoverned` in `_synthesisui/config.json`.": "Todo arquivo deste projeto é verificado no momento em que você o escreve, menos {out}, que você escreveu em `ungoverned` no `_synthesisui/config.json`.",
+    "Every file in this project is checked as you write it. To leave a place out, name it under `ungoverned` in `_synthesisui/config.json`.": "Todo arquivo deste projeto é verificado no momento em que você o escreve. Para deixar um lugar de fora, escreva-o em `ungoverned` no `_synthesisui/config.json`.",
+    "What this system knows was read from {scope}. {apps} declare a dependency on `{specifier}`, so they write in its vocabulary - nothing in them was read.": "O que este sistema sabe foi lido de {scope}. {apps} declaram dependência de `{specifier}`, então escrevem no vocabulário dele - nada dentro deles foi lido.",
+    "What this system knows was read from {scope} - nothing outside it was opened.": "O que este sistema sabe foi lido de {scope} - nada fora dali foi aberto.",
+    "A value this ruler cannot read is not a value it approved - silence here is never a pass.": "Um valor que esta régua não consegue ler não é um valor que ela aprovou - silêncio aqui nunca é aprovação.",
     // ── as descrições das skills ──
     "the first run, start to finish": "o primeiro uso, do início ao fim",
     "the import, orchestrated": "o import, orquestrado",

package/dist/doctor/idiom-names.js

@@ -0,0 +1,266 @@
+/**
+ * COMO ESTE PROJETO ESCREVE UM TOKEN - e por que a régua não enxergava a metade do trabalho dele.
+ *
+ * ═══ O QUE O CLIENTE VIA ═══
+ *
+ * Um arquivo da landing dele com **103 utilities do tema dele** recebia, do relatório de cobertura,
+ * **0 usos contados** (medido em 12/09, no `codelevel`). O contador só conhecia uma forma de
+ * apontar para um token - `var(--x)` -, e num projeto cujo idioma medido é utility a forma certa é
+ * outra: `bg-primary`, `p-6`, `rounded-lg`, `font-serif`.
+ *
+ * O efeito era um número que acusa quem fez tudo certo. A landing inteira escrita no vocabulário do
+ * sistema saía como `0%`, e ao lado dela um arquivo onde nada foi medido saía como `100%` - mesmo
+ * numerador, dois vereditos opostos.
+ *
+ * ═══ DE ONDE SAI A TRADUÇÃO, e ela não é nossa nem de um repositório ═══
+ *
+ * A ligação nome-de-token → utility é o CONTRATO PUBLICADO do Tailwind v4: uma custom property
+ * declarada num namespace de tema gera as utilities daquele namespace. `--color-primary` gera
+ * `bg-primary`, `text-primary`, `border-primary`; `--radius-lg` gera `rounded-lg`; `--font-serif`
+ * gera `font-serif`. Não há convenção de repositório nenhuma aqui - a tabela abaixo é a do
+ * framework, e um projeto que não declare nenhum desses namespaces recebe um índice VAZIO e se
+ * comporta exatamente como antes desta peça existir (`INV-GERAL-07`).
+ *
+ * ═══ O GATILHO É O BLOCO `@theme`, e não a forma do nome ═══
+ *
+ * A primeira versão derivava a grafia de QUALQUER nome declarado num namespace de tema, e a revisão
+ * de contrato derrubou isso com o caso certo: um projeto de CSS puro que declara
+ * `:root { --color-primary: #… }` - um nome banal - e veste classes de uma biblioteca de terceiro
+ * (`text-primary`, `bg-primary`) receberia três "usos do sistema dele" por elemento que não
+ * referencia o sistema dele nenhuma vez. Cobertura inflada é o pior sentido possível do erro: a
+ * plataforma diria que ele está em dia quando ele não está.
+ *
+ * `@theme` é a declaração pela qual o PROJETO diz ao compilador que aquelas utilities existem. É
+ * o opt-in dele, escrito na folha dele, e é isso que separa "eu uso este framework" de "eu tenho
+ * uma variável com um nome comum". Fora de um bloco desses, o índice fica vazio.
+ *
+ * ═══ A LACUNA, DECLARADA ═══
+ *
+ * Outro framework de utilities com outra tabela de namespaces não é lido por esta peça, e isso é
+ * dito (`INV-HOOK-07`) em vez de suposto: o índice fica vazio, a régua volta a contar só `var()`,
+ * e nada passa a valer mais do que vale. Ela nunca inventa um nome - só reconhece a grafia que o
+ * próprio compilador dele produziria a partir do que ele escreveu.
+ */
+/**
+ * OS NAMESPACES DE TEMA E AS UTILITIES QUE CADA UM GERA - a tabela do framework.
+ *
+ * Lida do mais específico para o menos: `--font-weight-medium` é do namespace `font-weight`
+ * (utility `font-medium`), não do namespace `font` com uma folha `weight-medium`. Sem a ordem, o
+ * mesmo nome produziria uma grafia que o compilador nunca emite, e contar uma grafia que não existe
+ * é o mesmo defeito que o `phantom` existe para impedir, do outro lado.
+ */
+const NAMESPACES = [
+    [
+        "color",
+        [
+            "bg",
+            "text",
+            "border",
+            "border-t",
+            "border-r",
+            "border-b",
+            "border-l",
+            "border-x",
+            "border-y",
+            "border-s",
+            "border-e",
+            "ring",
+            "inset-ring",
+            "fill",
+            "stroke",
+            "from",
+            "via",
+            "to",
+            "decoration",
+            "outline",
+            "accent",
+            "caret",
+            "divide",
+            "placeholder",
+            "shadow",
+            "inset-shadow",
+            "drop-shadow",
+            "text-shadow",
+        ],
+    ],
+    ["font-weight", ["font"]],
+    ["font", ["font"]],
+    ["text", ["text"]],
+    ["tracking", ["tracking"]],
+    ["leading", ["leading"]],
+    [
+        "spacing",
+        [
+            "p",
+            "px",
+            "py",
+            "pt",
+            "pr",
+            "pb",
+            "pl",
+            "ps",
+            "pe",
+            "m",
+            "mx",
+            "my",
+            "mt",
+            "mr",
+            "mb",
+            "ml",
+            "ms",
+            "me",
+            "gap",
+            "gap-x",
+            "gap-y",
+            "space-x",
+            "space-y",
+            "w",
+            "h",
+            "size",
+            "min-w",
+            "min-h",
+            "max-w",
+            "max-h",
+            "inset",
+            "inset-x",
+            "inset-y",
+            "top",
+            "right",
+            "bottom",
+            "left",
+            "start",
+            "end",
+            "translate",
+            "translate-x",
+            "translate-y",
+            "scroll-m",
+            "scroll-p",
+            "basis",
+            "indent",
+        ],
+    ],
+    [
+        "radius",
+        [
+            "rounded",
+            "rounded-t",
+            "rounded-r",
+            "rounded-b",
+            "rounded-l",
+            "rounded-tl",
+            "rounded-tr",
+            "rounded-br",
+            "rounded-bl",
+            "rounded-s",
+            "rounded-e",
+        ],
+    ],
+    ["inset-shadow", ["inset-shadow"]],
+    ["drop-shadow", ["drop-shadow"]],
+    ["text-shadow", ["text-shadow"]],
+    ["shadow", ["shadow"]],
+    ["blur", ["blur"]],
+    ["perspective", ["perspective"]],
+    ["aspect", ["aspect"]],
+    ["ease", ["ease"]],
+    ["animate", ["animate"]],
+    ["container", ["max-w"]],
+];
+/**
+ * OS NOMES QUE O PROJETO DECLARA DENTRO DE UM BLOCO `@theme` - e nada fora dele.
+ *
+ * O bloco é o opt-in do projeto naquele compilador: escrever `--color-primary` ali é dizer que
+ * `bg-primary` passa a existir. A mesma variável em `:root` é só uma variável.
+ *
+ * A varredura é por profundidade de chave, e não por regex de bloco, porque um `@theme` real
+ * carrega `@property` e comentários dentro dele em projetos que usam animação; contar chaves é o
+ * que não se confunde com isso.
+ */
+function themeNames(css) {
+    const out = [];
+    const opens = /@theme\b[^{]*\{/g;
+    for (const m of css.matchAll(opens)) {
+        let depth = 1;
+        let i = (m.index ?? 0) + m[0].length;
+        const start = i;
+        for (; i < css.length && depth > 0; i++) {
+            if (css[i] === "{")
+                depth++;
+            else if (css[i] === "}")
+                depth--;
+        }
+        const body = css.slice(start, i - 1);
+        for (const d of body.matchAll(/(--[a-z0-9_-]+)\s*:/gi))
+            out.push(d[1]);
+    }
+    return out;
+}
+/** Do mais longo para o mais curto, para `font-weight` ganhar de `font`. */
+const BY_DEPTH = [...NAMESPACES].sort((a, b) => b[0].split("-").length - a[0].split("-").length);
+/**
+ * AS GRAFIAS QUE ESTE SISTEMA GERA - `bg-primary` -> `--color-primary`.
+ *
+ * O valor é o NOME DECLARADO, e não um booleano, porque quem lê isto precisa dos dois lados: a
+ * régua só quer saber que a grafia existe, e a ligação regra↔código precisa dizer QUAL decisão do
+ * sistema saiu do arquivo.
+ *
+ * Um nome com modificador (`--text-lg--line-height`) fica de fora: ele não é um token endereçável,
+ * é a segunda metade de um que já está no índice.
+ */
+export function utilitySpellings(css) {
+    const out = new Map();
+    for (const raw of themeNames(css)) {
+        const name = raw.toLowerCase();
+        if (!name.startsWith("--"))
+            continue;
+        const bare = name.slice(2);
+        if (bare.includes("--"))
+            continue;
+        for (const [namespace, prefixes] of BY_DEPTH) {
+            if (!bare.startsWith(`${namespace}-`))
+                continue;
+            const leaf = bare.slice(namespace.length + 1);
+            if (!leaf)
+                break;
+            for (const prefix of prefixes) {
+                const spelling = `${prefix}-${leaf}`;
+                /** A primeira declaração vence, a mesma regra da colheita de custom properties. */
+                if (!out.has(spelling))
+                    out.set(spelling, name);
+            }
+            break;
+        }
+    }
+    return out;
+}
+/**
+ * UMA PALAVRA DE CLASSE NUMA LINHA - e as três coisas que ela NÃO pode ser.
+ *
+ * `bg-primary`, `md:p-6`, `hover:rounded-lg!`, `bg-primary/50`: a variante e o modificador ficam de
+ * fora do casamento porque o compilador também os separa do nome do token.
+ *
+ * O que este padrão recusa é o que estragaria a contagem:
+ *
+ *     `--font-serif: …`      a DECLARAÇÃO do token, que não é uso dele
+ *     `var(--font-serif)`    já contado pela régua de `var()` - contar aqui seria contar duas vezes
+ *     `font-serifed`         um nome maior que por acaso começa igual
+ *
+ * As três caem pela mesma guarda: o caractere ANTES não pode ser hífen, letra, dígito ou `_`.
+ */
+const CLASS_WORD = /[a-z][a-z0-9]*(?:-[a-z0-9.]+)+/g;
+/** As grafias deste sistema que esta linha realmente escreve. */
+export function utilitiesOn(line, utilities) {
+    if (utilities.size === 0)
+        return [];
+    const out = [];
+    for (const m of line.matchAll(CLASS_WORD)) {
+        const at = m.index ?? 0;
+        const before = at > 0 ? line[at - 1] : "";
+        if (before && /[-\w]/.test(before))
+            continue;
+        const name = utilities.get(m[0]);
+        if (name)
+            out.push(name);
+    }
+    return out;
+}

package/dist/doctor/ledger.js

@@ -118,7 +118,7 @@ export function unrepresentedFrom(findings, matched) {
     }
     return out;
 }
-const ledgerPath = (root) => join(root, "_synthesisui", LEDGER_FILE);
+export const ledgerPath = (root) => join(root, "_synthesisui", LEDGER_FILE);
 /** Keep the file from growing forever: past ~1MB, keep the newest half. A
  *  trend needs recent history, not an archive. */
 const MAX_BYTES = 1_000_000;
@@ -221,8 +221,14 @@ export async function readEvents(root) {
  * medido: `coverage 40% -> 0% since the first run` na cópia do `web-subscribe`, e `30% -> 28%` no
  * `frontend-hub`. O denominador cresceu porque a leitura melhorou, e comparar as duas fotos é
  * comparar réguas diferentes.
+ *
+ * A 4 é a utility do tema DELE entrando na conta (12/09): `bg-primary` aponta para
+ * `--color-primary` exatamente como `var(--color-primary)` aponta, e só a segunda forma era vista.
+ * Aqui o salto é para CIMA e é grande - num projeto cujo idioma medido é utility, quase todo
+ * apontamento estava fora da conta -, então comparar as duas fotos diria que alguém consertou o
+ * repositório num dia. Ver `idiom-names.ts`.
  */
-export const COVERAGE_RULE = 3;
+export const COVERAGE_RULE = 4;
 /**
  * POR QUE A TENDÊNCIA RECOMEÇOU - uma frase por régua, e a saída lê ESTA, nunca uma fixa.
  *
@@ -233,6 +239,7 @@ export const COVERAGE_RULE = 3;
 export const COVERAGE_RULE_REASON = {
     2: "your own tokens count now too",
     3: "every length in a shorthand counts now - `padding: 8px 24px` was one value and is two",
+    4: "the utilities of your own theme count now - `bg-primary` points at `--color-primary` the same way `var(--color-primary)` does",
 };
 export function summarize(events) {
     const hooks = events.filter((e) => e.kind === "hook" && e.file);

package/dist/doctor/scan.js

@@ -9,6 +9,7 @@
  * Text in, findings out. No filesystem, no AST, no network - a diagnosis that
  * takes eight seconds and needs a build step is a diagnosis nobody runs.
  */
+import { utilitiesOn } from "./idiom-names.js";
 import { normalizeValue, tokenMatch } from "./tokens.js";
 /**
  * O NOME QUE SE ESCREVE NO ARQUIVO DELE - e existe uma função só para isto por um motivo.
@@ -241,6 +242,23 @@ const unjudgeable = (name, line) => {
         line.startsWith("*") ||
         line.startsWith("/*"));
 };
+/**
+ * QUANTAS VEZES ESTA LINHA APONTA PARA UM TOKEN - nas DUAS formas de apontar.
+ *
+ * ═══ O QUE O CLIENTE VIA, medido em 12/09 no `codelevel` ═══
+ *
+ * Um arquivo da landing dele com **103 utilities do tema dele** era contado com **0 usos**. O
+ * contador conhecia uma forma só - `var(--x)` -, e o idioma medido daquele projeto é outro:
+ * `conventions[".tsx"].idiom = "tailwind-utility"`, share 72,3%. A régua media com a régua do
+ * idioma vizinho, então quem escreveu a landing inteira no vocabulário do próprio sistema recebia
+ * a mesma nota de quem não usou nada dele.
+ *
+ * ═══ E A SEGUNDA FORMA SAI DO QUE ELE DECLAROU ═══
+ *
+ * `table.utilities` é derivada dos namespaces de tema que o sistema dele declara, pelo contrato
+ * publicado do framework - ver `idiom-names.ts`. Um sistema sem nenhum desses namespaces devolve
+ * índice vazio, e esta função volta a ser exatamente a de antes.
+ */
 function countTokenUses(line, table) {
     let n = 0;
     const judge = canJudgeDsNames(table);
@@ -253,7 +271,7 @@ function countTokenUses(line, table) {
         if (isKnownToken(name, table))
             n++;
     }
-    return n;
+    return n + utilitiesOn(line, table.utilities).length;
 }
 /** The undeclared `--ds-` names on a line, for the report. Same rules as the
  *  counter above, so a name is never both uncounted and unmentioned. */
@@ -880,7 +898,25 @@ export function diagnose(files) {
         named: flat.filter((f) => nameToWrite(f)).length,
         tokenUses,
         phantomUses,
-        coverage: total === 0 ? 100 : Math.round(((tokenUses + ownUses) / total) * 100),
+        reach: 
+        /**
+         * NADA FOI ABERTO é diferente de ABRI E NÃO HAVIA NADA - achado da revisão de QA no fecho,
+         * e o terceiro caso existia no tipo sem nenhum produtor.
+         *
+         * Um caminho fora do escopo lido, uma pasta sem arquivo legível, um alvo que o filtro
+         * recusou: ali a régua não mediu, e um percentual - qualquer percentual - seria uma nota
+         * sobre um exame que não aconteceu.
+         */
+        files.length === 0
+            ? { measured: false, why: "never measured" }
+            : total === 0
+                ? { measured: false, why: "nothing here carries a design value" }
+                : {
+                    measured: true,
+                    percent: Math.round(((tokenUses + ownUses) / total) * 100),
+                    uses: tokenUses + ownUses,
+                    of: total,
+                },
         ownTokens: ownDeclared.size,
         ownUses,
         ownMirrored,

package/dist/doctor/tokens.js

@@ -11,6 +11,7 @@
  * Pure and dependency-free on purpose: every function here takes text and
  * returns data, so the whole diagnosis is testable without a filesystem.
  */
+import { utilitySpellings } from "./idiom-names.js";
 import { DEFAULT_ROOT_PX } from "./root-size.js";
 import { parseSchemeBlocks } from "./scheme-blocks.js";
 import { compiledNames } from "./their-compiled-names.js";
@@ -25,6 +26,7 @@ export const EMPTY_TABLE = {
     rootFrom: null,
     aliases: new Map(),
     declared: new Set(),
+    utilities: new Map(),
     compiledAway: new Map(),
     keyframes: new Set(),
 };
@@ -368,6 +370,7 @@ export function buildTable(input) {
         else
             byCompiledValue.set(key, [one]);
     }
+    const declaredNames = parseDeclaredNames(input.css);
     const byValue = new Map();
     for (const [name, value] of resolved) {
         const key = normalizeValue(value, rootPx);
@@ -390,7 +393,12 @@ export function buildTable(input) {
         rootFrom: input.rootFrom ?? null,
         /** Vazio até `withTheirNames` ler o vocabulário dele - ver `their-names.ts`. */
         aliases: new Map(),
-        declared: parseDeclaredNames(input.css),
+        declared: declaredNames,
+        /**
+         * Derivada do que ELE DECLAROU NUM BLOCO `@theme`, nunca da forma de um nome - ver
+         * `idiom-names.ts`, onde está o caso que a régua por forma quebrava.
+         */
+        utilities: utilitySpellings(input.css),
         compiledAway: byCompiledValue,
         keyframes: new Set([...input.css.matchAll(/@keyframes\s+([a-zA-Z0-9_-]+)/g)].map((m) => m[1])),
     };

package/dist/governed.js

@@ -0,0 +1,53 @@
+import { readProjectConfig } from "./config.js";
+/**
+ * O QUE ESTA CHECAGEM OLHA - e a resposta é UMA, lida do mesmo lugar por quem verifica e por quem
+ * explica.
+ *
+ * ═══ O DEFEITO QUE ISTO FECHA - achado da revisão de contrato no fecho da etapa 21 ═══
+ *
+ * Havia três réguas respondendo "o que está governado". O `import` derivava dos `package.json`; a
+ * frase que o `connect` imprime derivava de `census.adoption.consumers`, que só existe quando
+ * alguém digitou `--usage`; e a checagem em si não consultava nenhuma das duas - ela olhava TODO
+ * arquivo de UI do repositório.
+ *
+ * O efeito num cliente que nunca digitou `--usage`: a tela dizia *"verificado aqui: packages/ui"* e
+ * fechava com *"em qualquer outro lugar nada é lido"*, enquanto a checagem estava lendo `apps/`,
+ * `packages/db` e tudo o mais. **Lacuna declarada ERRADA é pior que lacuna calada**: ele confia num
+ * limite que não existe.
+ *
+ * ═══ A REGRA, e ela é a mais simples possível ═══
+ *
+ * Todo arquivo onde um valor de design pode aparecer está governado, menos o que é NOSSO e menos o
+ * que ELE declarou fora. Não há lista de entrada: uma lista de "governados" escrita à mão envelhece
+ * no dia em que um app novo importa a biblioteca, e aí o produto cala sobre o lugar mais novo do
+ * repositório.
+ */
+/** Arquivos onde um valor de design pode aparecer. Um README não tem o que ser checado. */
+export const UI_FILE = /\.(tsx|jsx|ts|js|css|scss|vue|svelte)$/i;
+/** O que ELE tirou da governança, lido do arquivo do repositório dele. */
+export async function ungovernedIn(root) {
+    return (await readProjectConfig(root).catch(() => null))?.ungoverned ?? [];
+}
+/**
+ * Este caminho relativo está sob a checagem?
+ *
+ * Três recusas, e cada uma fecha um caso real:
+ *
+ *     fora do projeto              não é da nossa conta
+ *     é artefato nosso             `_synthesisui/` é a resposta, nunca o problema
+ *     ele declarou fora            `ungoverned` em `_synthesisui/config.json`
+ *
+ * O CAMINHO TESTADO É O RELATIVO - achado da revisão de QA no fecho da etapa 20.
+ * `abs.includes("_synthesisui")` olhava o caminho ABSOLUTO, então quem clonasse o projeto para
+ * qualquer diretório com esse nome no meio (`~/_synthesisui-demo/app`) tinha TODOS os arquivos
+ * pulados e uma checagem permanentemente muda.
+ */
+export function governs(rel, ungoverned) {
+    if (rel.startsWith(".."))
+        return false;
+    if (!UI_FILE.test(rel))
+        return false;
+    if (rel.split("/").includes("_synthesisui"))
+        return false;
+    return !ungoverned.some((p) => rel === p || rel.startsWith(`${p}/`));
+}

package/dist/guarantee.js

@@ -0,0 +1,171 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { hasHook } from "./agent-wiring.js";
+import { ungovernedIn } from "./governed.js";
+/**
+ * ATÉ ONDE A GARANTIA VAI - dito uma vez, com número, e sem virar ruído.
+ *
+ * ═══ O QUE O CLIENTE VIVIA ═══
+ *
+ * A checagem que roda a cada escrita é parcial por construção, e nada dizia isso. Ela compara o
+ * arquivo contra o último commit, então num arquivo que o git nunca viu a metade que fala de regra
+ * fica INERTE - e ficava inerte em silêncio. Ela lê duas formas de apontar para um token, e num
+ * projeto que escreve de uma terceira ela concordaria calada. Ela governa os apps que consomem a
+ * biblioteca, e ele não tinha como saber disso nem como sair.
+ *
+ * Nenhuma dessas três é defeito: são fronteiras. O defeito é confundir fronteira com aprovação -
+ * uma checagem que cala parece uma checagem que aprovou, e é assim que alguém confia numa garantia
+ * parcial sem saber que ela é parcial. A lei 8 já dizia: lacuna declarada é confiança, lacuna
+ * calada é bug.
+ *
+ * ═══ POR QUE UMA VEZ, E NÃO A CADA RODADA ═══
+ *
+ * Esta é a mesma tensão do hook: um aviso que aparece sempre é um aviso que a pessoa aprende a
+ * pular, e aí ele não serve para a vez em que era mesmo necessário. Então o texto sai quando a
+ * RESPOSTA é nova - a primeira vez, e depois só quando ela muda. A impressão digital do que foi
+ * dito fica ao lado do sistema, e quem apaga o sistema apaga a memória junto.
+ *
+ * ═══ E TODO NÚMERO AQUI É MEDIDO ═══
+ *
+ * Quantas grafias o idioma dele gera, quais lugares estão governados, o que ele declarou fora:
+ * tudo sai do vocabulário que o sistema declara, da medição que a esteira guardou e do arquivo de
+ * configuração que é dele. Nada aqui é uma promessa escrita à mão.
+ */
+/** Onde mora a impressão digital do que já foi dito - ver o cabeçalho. */
+const SAID = "_synthesisui/.guarantee";
+async function measuredPlaces(root) {
+    const raw = await readFile(join(root, "_synthesisui", "census.json"), "utf8").catch(() => "");
+    if (!raw)
+        return { scope: null, consumers: [], specifier: null };
+    try {
+        const parsed = JSON.parse(raw);
+        const scope = typeof parsed.scope === "string" && parsed.scope.trim()
+            ? parsed.scope.trim()
+            : null;
+        const listed = Array.isArray(parsed.adoption?.consumers)
+            ? (parsed.adoption?.consumers).filter((c) => c && typeof c.label === "string")
+            : [];
+        /**
+         * `usage` É A QUEDA, e ela existe para um projeto medido antes de a adoção viajar no arquivo:
+         * ali os dois apps estão gravados como caminhos, sem a contagem. Dizer o lugar sem o número é
+         * pior que não dizer? Não - o lugar é o que ele precisa para saber onde a garantia vale.
+         */
+        const usage = Array.isArray(parsed.usage)
+            ? parsed.usage.filter((u) => typeof u === "string" && !!u.trim())
+            : [];
+        const consumers = listed.length > 0
+            ? listed
+            : usage.map((label) => ({ label, files: 0, using: 0 }));
+        return {
+            scope,
+            consumers,
+            specifier: typeof parsed.adoption?.specifier === "string"
+                ? parsed.adoption.specifier
+                : null,
+        };
+    }
+    catch {
+        return { scope: null, consumers: [], specifier: null };
+    }
+}
+/**
+ * O QUE A CHECAGEM ALCANÇA NESTE PROJETO - `null` quando não há sistema instalado.
+ *
+ * Sem sistema não há garantia a delimitar, e uma seção explicando as fronteiras de algo que não
+ * está ligado é a definição de ruído.
+ */
+export async function guarantee(root, 
+/**
+ * O VOCABULÁRIO DO SISTEMA INSTALADO - passado por quem já o carregou.
+ *
+ * `connect` lê o sistema de qualquer forma; carregá-lo de novo aqui pagaria a varredura duas
+ * vezes na tela em que a pessoa está esperando.
+ */
+system) {
+    if (!system.name)
+        return null;
+    const { scope, consumers, specifier } = await measuredPlaces(root);
+    /**
+     * A GOVERNANÇA VEM DA MESMA FUNÇÃO QUE A CHECAGEM USA - ver `governed.ts`.
+     *
+     * Ela vinha de `census.adoption.consumers`, que só existe quando alguém digitou `--usage`, e a
+     * checagem nunca consultou aquilo: num cliente que não digitou, esta seção afirmava um limite
+     * que não existia. Lacuna declarada ERRADA é pior que lacuna calada.
+     */
+    const out = await ungovernedIn(root);
+    const wired = await hasHook(root).catch(() => false);
+    const lines = [];
+    const plain = (text) => ({ text, values: {} });
+    lines.push(plain(wired
+        ? "Every file this project writes is checked as it is written - by an edit tool or by a shell command, it makes no difference."
+        : "Nothing is checked automatically here yet: this project has no write check installed."));
+    /**
+     * A METADE QUE FICA INERTE SEM "ANTES" - e é a lacuna que ele mais sente, porque ela é
+     * invisível: um arquivo novo nunca apagou nada, então a checagem cala com razão e a pessoa lê
+     * esse silêncio como aprovação.
+     */
+    lines.push(plain("What a file no longer has is measured against your last commit. A file git has never seen has no before, so nothing is reported as removed there."));
+    lines.push(system.utilities.size > 0
+        ? {
+            text: "A value counts as coming from your system in two spellings: `var(--token)`, and the {n} utility names your own theme generates - `bg-primary`, `p-6`, `rounded-lg`.",
+            values: { n: String(system.utilities.size) },
+        }
+        : plain("A value counts as coming from your system when it is written as `var(--token)`. This system declares no theme names, so a utility class is not read as a reference to it."));
+    /**
+     * ONDE, e a frase é a REGRA e não uma lista de lugares.
+     *
+     * A primeira versão listava o escopo medido e os consumidores e fechava com *"em qualquer outro
+     * lugar nada é lido"* - falso, porque a checagem olha todo arquivo de UI do repositório. Agora
+     * ela diz a regra que o código aplica, e a única lista que aparece é a que ELE escreveu.
+     */
+    lines.push(out.length > 0
+        ? {
+            text: "Every file in this project is checked as you write it, except {out}, which you named under `ungoverned` in `_synthesisui/config.json`.",
+            values: { out: out.map((p) => `\`${p}\``).join(", ") },
+        }
+        : plain("Every file in this project is checked as you write it. To leave a place out, name it under `ungoverned` in `_synthesisui/config.json`."));
+    /**
+     * E DE ONDE O SISTEMA FOI LIDO - outra pergunta, e por isso outra frase.
+     *
+     * Ler e vigiar não são a mesma coisa: a esteira abriu `packages/ui` e o que ela sabe sobre design
+     * vem dali. Um app que só CONSOME a biblioteca é vigiado na escrita sem nunca ter sido lido, e
+     * juntar as duas numa frase foi o que produziu um limite falso.
+     */
+    if (scope)
+        lines.push(consumers.length > 0 && specifier
+            ? {
+                text: "What this system knows was read from {scope}. {apps} declare a dependency on `{specifier}`, so they write in its vocabulary - nothing in them was read.",
+                values: {
+                    scope: `\`${scope}\``,
+                    apps: consumers.map((c) => `\`${c.label}\``).join(", "),
+                    specifier,
+                },
+            }
+            : {
+                text: "What this system knows was read from {scope} - nothing outside it was opened.",
+                values: { scope: `\`${scope}\`` },
+            });
+    lines.push(plain("A value this ruler cannot read is not a value it approved - silence here is never a pass."));
+    return {
+        lines,
+        fingerprint: lines
+            .map((l) => `${l.text}|${Object.values(l.values).join(",")}`)
+            .join("\n"),
+    };
+}
+/**
+ * AS LINHAS, SE ELAS AINDA NÃO FORAM DITAS - e `null` quando a resposta é a mesma de antes.
+ *
+ * A escrita acontece ANTES de a frase sair, pelo mesmo motivo da saudação do hook: uma escrita que
+ * falha não pode produzir um produto que repete o mesmo parágrafo para sempre.
+ */
+export async function guaranteeIfNew(root, system) {
+    const answer = await guarantee(root, system).catch(() => null);
+    if (!answer)
+        return null;
+    const before = await readFile(join(root, SAID), "utf8").catch(() => "");
+    if (before.trim() === answer.fingerprint.trim())
+        return null;
+    await writeFile(join(root, SAID), `${answer.fingerprint}\n`, "utf8").catch(() => { });
+    return answer.lines;
+}