@shiftleftpt/sbd-toe-mcp 0.20.0-beta.20 → 0.20.0-beta.22

package/dist/tools/prepare-codegen-context.js

@@ -33,7 +33,7 @@ import { servedKgReleaseTag } from "../version-info.js";
 import { expandQueryWithAliases } from "../backend/semantic-index-gateway.js";
 import { requirementCategoryOf } from "../serving/requirement-id.js";
 import { prepareCodegenAffordances } from "../serving/affordances.js";
-import { runSelectionWithActivation } from "../serving/selection.js";
+import { runSelectionWithActivation, normalizeDeclaredTechnologies, stackTokensFromVocabulary } from "../serving/selection.js";
 import { REQUIREMENT_CEILING_BY_DETAIL, COST_PER_REQ_TK, BASE_TK, PAYLOAD_PROMISE_TK, projectedCostTk } from "../serving/payload-ceilings.js";
 const EVIDENCE_PATTERN_CAP = 25;
 /**
@@ -275,7 +275,24 @@ const TASK_TERM_TO_CONCERNS = [
  * categories. Keys are concerns added by this module. The categories map to
  * existing runtime v0 categories so the v0 requirement filter still works.
  */
-const CONCERN_TO_V0_CATEGORIES_SUPPLEMENT = {
+/**
+ * Declared context activators (G-mp1a/D3). Module scope + exported since
+ * 0.20.0-beta.21 (declarative-first): `sbd://toe/activation-vocabulary` publishes
+ * them — the vocabulary IS the contract, so it is derived from these tables and
+ * never restated by hand.
+ */
+export const EXPOSURE_CONCERNS = {
+    internal: ["auth", "logging"],
+    authenticated: ["auth", "logging"],
+    public: ["auth", "logging", "api", "validation", "architecture"]
+};
+export const SENSITIVITY_CONCERNS = {
+    // v1.8.0: personal/regulated data now also activates the PRI catalogue (privacy).
+    personal: ["encryption", "validation", "logging", "privacy"],
+    regulated: ["encryption", "validation", "logging", "privacy"],
+    secrets: ["secrets"]
+};
+export const CONCERN_TO_V0_CATEGORIES_SUPPLEMENT = {
     // Existing concerns intentionally left empty — fall back to ontology.concernsMap.
     auth: [],
     logging: [],
@@ -589,7 +606,8 @@ function recordActivation(trace, concerns, scores, rejected, entry, targetConcer
         trace.push(entry);
     }
 }
-export function activate(input) {
+export function activate(input, options = {}) {
+    const declaredOnly = options.declaredOnly ?? false;
     const trace = [];
     const rejected = [];
     const notes = [];
@@ -616,110 +634,118 @@ export function activate(input) {
             reason: `Concern '${unknown}' is not in the WP5/WP6 lexicon (${VALID_CONCERNS.join(", ")}).`
         });
     }
-    // 2) Alias expansion + direct task-term matches.
-    const { expanded, appliedAliases } = expandTaskText(input.taskLower);
-    for (const alias of appliedAliases) {
-        notes.push(`alias_expansion: '${alias.pt}' -> [${alias.en.join(", ")}]`);
-    }
-    // 2a) Compound phrases (run first — they encode canonical multi-domain asks).
-    // Whole-word match prevents accidental hits inside larger tokens.
-    for (const [phrase, mapped] of COMPOUND_TERM_TO_CONCERNS) {
-        if (!taskMatchesKeyword(expanded, phrase))
-            continue;
-        for (const concern of mapped) {
-            recordActivation(trace, concerns, concernScores, rejected, {
-                source: "compound_term",
-                produced: concern,
-                trigger: phrase,
-                score: 0.7,
-                confidence: "semantic",
-                reason: `Compound phrase '${phrase}' activates ${concern}.`
-            }, concern, { capDuplicates: true });
+    // 0.20.0-beta.21 — DECLARATIVO PRIMEIRO: tudo o que se segue até ao bloco 4 é
+    // INFERÊNCIA SOBRE PROSA/PATHS (termos da tarefa, aliases, compostos, homónimo
+    // da imagem, intenções, e as heurísticas de NOME de ficheiro). No caminho
+    // declarativo (default nesta linha) NÃO corre: o servidor responde ao que lhe
+    // declararam. Fica disponível em mode="discover" — instrumento de investigação
+    // (oráculo histórico + estudo de paráfrase), marcado exploratório na resposta.
+    if (!declaredOnly) {
+        // 2) Alias expansion + direct task-term matches.
+        const { expanded, appliedAliases } = expandTaskText(input.taskLower);
+        for (const alias of appliedAliases) {
+            notes.push(`alias_expansion: '${alias.pt}' -> [${alias.en.join(", ")}]`);
         }
-    }
-    // 2b) Single-token task terms. Whole-word matching prevents false positives
-    // like `test` inside `latest` or `log` inside `logical`.
-    for (const [term, mapped] of TASK_TERM_TO_CONCERNS) {
-        if (!taskMatchesKeyword(expanded, term))
-            continue;
-        const viaAlias = !taskMatchesKeyword(input.taskLower, term) &&
-            appliedAliases.some((alias) => alias.en.includes(term));
-        for (const concern of mapped) {
-            recordActivation(trace, concerns, concernScores, rejected, {
-                source: viaAlias ? "alias_expansion" : "task_term",
-                produced: concern,
-                trigger: term,
-                score: viaAlias ? 0.6 : 0.8,
-                confidence: viaAlias ? "semantic" : "deterministic",
-                reason: viaAlias
-                    ? `Task text matches '${term}' after PT/EN alias expansion.`
-                    : `Task text contains '${term}'.`
-            }, concern, { capDuplicates: true });
-        }
-    }
-    // 2b-bis) R-image (vaga v1.8.0, 2026-08-31): "image"/"imagem" é homónimo —
-    // imagem de container vs ficheiro de imagem (finding do replay DualGauge).
-    // Desambiguação DECLARADA por contexto: image+docker/registry/container → sentido
-    // container (deployment/distribution); image+file/upload/photo → FIL (files);
-    // ambos os contextos → ambos; nenhum → sentido histórico (deployment/distribution).
-    if (taskMatchesKeyword(expanded, "image")) {
-        const containerCtx = /docker|registry|container|kubernetes|k8s|\boci\b/.test(expanded);
-        const fileCtx = /upload|file|photo|picture|png|jpe?g|gif|avatar|galeria|gallery|perfil|profile/.test(expanded);
-        const senses = [];
-        if (fileCtx) {
-            senses.push({ concern: "files", reason: "R-image: 'image' em contexto file/upload/photo → ficheiro de imagem (FIL)" });
+        // 2a) Compound phrases (run first — they encode canonical multi-domain asks).
+        // Whole-word match prevents accidental hits inside larger tokens.
+        for (const [phrase, mapped] of COMPOUND_TERM_TO_CONCERNS) {
+            if (!taskMatchesKeyword(expanded, phrase))
+                continue;
+            for (const concern of mapped) {
+                recordActivation(trace, concerns, concernScores, rejected, {
+                    source: "compound_term",
+                    produced: concern,
+                    trigger: phrase,
+                    score: 0.7,
+                    confidence: "semantic",
+                    reason: `Compound phrase '${phrase}' activates ${concern}.`
+                }, concern, { capDuplicates: true });
+            }
         }
-        if (containerCtx || !fileCtx) {
-            senses.push({ concern: "deployment", reason: containerCtx ? "R-image: 'image' em contexto docker/registry/container → imagem de container" : "R-image: 'image' sem contexto discriminante → sentido histórico (deployment)" }, { concern: "distribution", reason: containerCtx ? "R-image: 'image' em contexto docker/registry/container → distribuição de imagem" : "R-image: 'image' sem contexto discriminante → sentido histórico (distribution)" });
+        // 2b) Single-token task terms. Whole-word matching prevents false positives
+        // like `test` inside `latest` or `log` inside `logical`.
+        for (const [term, mapped] of TASK_TERM_TO_CONCERNS) {
+            if (!taskMatchesKeyword(expanded, term))
+                continue;
+            const viaAlias = !taskMatchesKeyword(input.taskLower, term) &&
+                appliedAliases.some((alias) => alias.en.includes(term));
+            for (const concern of mapped) {
+                recordActivation(trace, concerns, concernScores, rejected, {
+                    source: viaAlias ? "alias_expansion" : "task_term",
+                    produced: concern,
+                    trigger: term,
+                    score: viaAlias ? 0.6 : 0.8,
+                    confidence: viaAlias ? "semantic" : "deterministic",
+                    reason: viaAlias
+                        ? `Task text matches '${term}' after PT/EN alias expansion.`
+                        : `Task text contains '${term}'.`
+                }, concern, { capDuplicates: true });
+            }
         }
-        for (const { concern, reason } of senses) {
-            recordActivation(trace, concerns, concernScores, rejected, { source: "task_term", produced: concern, trigger: "image", score: 0.8, confidence: "deterministic", reason }, concern, { capDuplicates: true });
+        // 2b-bis) R-image (vaga v1.8.0, 2026-08-31): "image"/"imagem" é homónimo —
+        // imagem de container vs ficheiro de imagem (finding do replay DualGauge).
+        // Desambiguação DECLARADA por contexto: image+docker/registry/container → sentido
+        // container (deployment/distribution); image+file/upload/photo → FIL (files);
+        // ambos os contextos → ambos; nenhum → sentido histórico (deployment/distribution).
+        if (taskMatchesKeyword(expanded, "image")) {
+            const containerCtx = /docker|registry|container|kubernetes|k8s|\boci\b/.test(expanded);
+            const fileCtx = /upload|file|photo|picture|png|jpe?g|gif|avatar|galeria|gallery|perfil|profile/.test(expanded);
+            const senses = [];
+            if (fileCtx) {
+                senses.push({ concern: "files", reason: "R-image: 'image' em contexto file/upload/photo → ficheiro de imagem (FIL)" });
+            }
+            if (containerCtx || !fileCtx) {
+                senses.push({ concern: "deployment", reason: containerCtx ? "R-image: 'image' em contexto docker/registry/container → imagem de container" : "R-image: 'image' sem contexto discriminante → sentido histórico (deployment)" }, { concern: "distribution", reason: containerCtx ? "R-image: 'image' em contexto docker/registry/container → distribuição de imagem" : "R-image: 'image' sem contexto discriminante → sentido histórico (distribution)" });
+            }
+            for (const { concern, reason } of senses) {
+                recordActivation(trace, concerns, concernScores, rejected, { source: "task_term", produced: concern, trigger: "image", score: 0.8, confidence: "deterministic", reason }, concern, { capDuplicates: true });
+            }
         }
-    }
-    // 2c) Whole-word intent classification (codegen-specific; stricter than the
-    // gateway's substring matcher to avoid PT/EN false positives).
-    for (const intentEntry of CODEGEN_INTENTS) {
-        const matchedKeyword = intentEntry.keywords.find((keyword) => taskMatchesKeyword(expanded, keyword));
-        if (!matchedKeyword)
-            continue;
-        for (const concern of intentEntry.concerns) {
-            recordActivation(trace, concerns, concernScores, rejected, {
-                source: "intent_keyword",
-                produced: concern,
-                trigger: intentEntry.intent,
-                score: 0.5,
-                confidence: "semantic",
-                reason: `Intent '${intentEntry.intent}' matched keyword '${matchedKeyword}'.`
-            }, concern, { capDuplicates: false });
+        // 2c) Whole-word intent classification (codegen-specific; stricter than the
+        // gateway's substring matcher to avoid PT/EN false positives).
+        for (const intentEntry of CODEGEN_INTENTS) {
+            const matchedKeyword = intentEntry.keywords.find((keyword) => taskMatchesKeyword(expanded, keyword));
+            if (!matchedKeyword)
+                continue;
+            for (const concern of intentEntry.concerns) {
+                recordActivation(trace, concerns, concernScores, rejected, {
+                    source: "intent_keyword",
+                    produced: concern,
+                    trigger: intentEntry.intent,
+                    score: 0.5,
+                    confidence: "semantic",
+                    reason: `Intent '${intentEntry.intent}' matched keyword '${matchedKeyword}'.`
+                }, concern, { capDuplicates: false });
+            }
         }
-    }
-    // 3) Changed-file path heuristics.
-    for (const file of input.changed_files) {
-        const lower = file.toLowerCase();
-        const fileHits = [];
-        if (/route|router|controller|handler|endpoint/.test(lower))
-            fileHits.push("api");
-        if (/auth|session|jwt|login/.test(lower))
-            fileHits.push("auth");
-        if (/log|logger/.test(lower))
-            fileHits.push("logging");
-        if (/config|env|settings/.test(lower))
-            fileHits.push("config");
-        if (/secret|credential/.test(lower))
-            fileHits.push("secrets");
-        if (/test|spec/.test(lower))
-            fileHits.push("testing");
-        if (/dockerfile|docker-compose|k8s|kubernetes|terraform/.test(lower))
-            fileHits.push("deployment");
-        for (const concern of fileHits) {
-            recordActivation(trace, concerns, concernScores, rejected, {
-                source: "changed_file",
-                produced: concern,
-                trigger: file,
-                score: 0.5,
-                confidence: "semantic",
-                reason: `Changed file path matches '${concern}' heuristics.`
-            }, concern, { capDuplicates: true });
+        // 3) Changed-file path heuristics.
+        for (const file of input.changed_files) {
+            const lower = file.toLowerCase();
+            const fileHits = [];
+            if (/route|router|controller|handler|endpoint/.test(lower))
+                fileHits.push("api");
+            if (/auth|session|jwt|login/.test(lower))
+                fileHits.push("auth");
+            if (/log|logger/.test(lower))
+                fileHits.push("logging");
+            if (/config|env|settings/.test(lower))
+                fileHits.push("config");
+            if (/secret|credential/.test(lower))
+                fileHits.push("secrets");
+            if (/test|spec/.test(lower))
+                fileHits.push("testing");
+            if (/dockerfile|docker-compose|k8s|kubernetes|terraform/.test(lower))
+                fileHits.push("deployment");
+            for (const concern of fileHits) {
+                recordActivation(trace, concerns, concernScores, rejected, {
+                    source: "changed_file",
+                    produced: concern,
+                    trigger: file,
+                    score: 0.5,
+                    confidence: "semantic",
+                    reason: `Changed file path matches '${concern}' heuristics.`
+                }, concern, { capDuplicates: true });
+            }
         }
     }
     // 4) Slice families (ranked by max contributing concern score).
@@ -734,7 +760,11 @@ export function activate(input) {
             sliceFamilyScores.set(family, score);
         }
         trace.push({
-            source: "task_term",
+            // 0.20.0-beta.22 (P2-A): isto NUNCA foi um termo da tarefa — é o mapeamento
+            // determinístico concern → slice family. A etiqueta `task_term` era órfã do
+            // motor lexical e aparecia mesmo com `task` vazio. Em `discover` o task_term
+            // legítimo (casamento de palavras) mantém-se; aqui a fonte diz o que é.
+            source: declaredOnly ? "concern_slice_mapping" : "task_term",
             produced: family,
             trigger: concern,
             score,
@@ -747,11 +777,6 @@ export function activate(input) {
     // rule (each with its own trace source), because the reference selection
     // semantics says an authenticated/public surface must be auditable and a
     // personal/regulated data context must carry crypto+masking+validation.
-    const EXPOSURE_CONCERNS = {
-        internal: ["auth", "logging"],
-        authenticated: ["auth", "logging"],
-        public: ["auth", "logging", "api", "validation", "architecture"]
-    };
     if (input.exposure && EXPOSURE_CONCERNS[input.exposure]) {
         for (const concern of EXPOSURE_CONCERNS[input.exposure] ?? []) {
             recordActivation(trace, concerns, concernScores, rejected, {
@@ -764,12 +789,6 @@ export function activate(input) {
             }, concern, { capDuplicates: true });
         }
     }
-    const SENSITIVITY_CONCERNS = {
-        // v1.8.0: personal/regulated data now also activates the PRI catalogue (privacy).
-        personal: ["encryption", "validation", "logging", "privacy"],
-        regulated: ["encryption", "validation", "logging", "privacy"],
-        secrets: ["secrets"]
-    };
     if (input.data_sensitivity && SENSITIVITY_CONCERNS[input.data_sensitivity]) {
         for (const concern of SENSITIVITY_CONCERNS[input.data_sensitivity] ?? []) {
             recordActivation(trace, concerns, concernScores, rejected, {
@@ -782,6 +801,22 @@ export function activate(input) {
             }, concern, { capDuplicates: true });
         }
     }
+    // 5-pre) 0.20.0-beta.22 (P1-D): o `stack` é a ÚNICA leitura de texto que resta no
+    // caminho declarativo (token EXACTO de um conjunto fechado — normalizar o declarado).
+    // Deixava de fora o rasto: os capítulos apareciam sem que o auditor pudesse ver
+    // porquê. Agora cada token reconhecido emite a sua entrada.
+    if (declaredOnly && input.stack) {
+        for (const token of stackTokensFromVocabulary(input.stack)) {
+            trace.push({
+                source: "stack_token",
+                produced: token,
+                trigger: "stack",
+                score: 0.9,
+                confidence: "deterministic",
+                reason: `token exacto de \`technologies\` encontrado em \`stack\`: '${token}' (normalização de valor declarado; o texto livre à volta é ignorado)`
+            });
+        }
+    }
     // 5) Risk level (informational trace entry, no concern activation).
     if (input.risk_level) {
         trace.push({
@@ -877,13 +912,19 @@ function gateBeforeActivation(input) {
 }
 function gateAfterActivation(args) {
     const { input, activation, estimatedRequirements } = args;
+    const declaredSurfaces = args.declaredSurfaces === true;
     const reasons = [];
     const suggestions = [];
     // P3 do ciclo MP1 (2026-08-31): o gate conta SUPERFÍCIES (famílias dos concerns
     // primários de cada sinal), não o total de famílias activadas — concerns de
     // suporte de um mesmo sinal (mtls→secrets, mensageria→logging) não pedem
     // decomposição. GC-10 é o caso de referência: 1 integração legítima.
-    if (activation.decompositionFamilies.length > 3) {
+    // 0.20.0-beta.21 («declarativo primeiro»): o gate de decomposição nasceu para travar
+    // pedidos VAGOS cuja prosa activava meio catálogo. Quando as famílias vêm de
+    // DECLARAÇÕES explícitas, bloquear contradiz o contrato — o chamador não foi vago,
+    // foi preciso. O guarda do tamanho da resposta passa a ser (e já era) o tecto de
+    // requisitos por detail (0.19.4). Em `discover` a regra mantém-se tal e qual.
+    if (!declaredSurfaces && activation.decompositionFamilies.length > 3) {
         reasons.push(`Pedido activa ${activation.decompositionFamilies.length} superfícies (famílias primárias: ${activation.decompositionFamilies.join(", ")}) — máximo recomendado: 3. Concerns de suporte do mesmo sinal não contam.`);
         suggestions.push("Reparte por slice family. Cada PR/PR-step deve ficar em 1–3 slices.");
     }
@@ -896,7 +937,7 @@ function gateAfterActivation(args) {
     // D1 (G-mp1a): with the requirement-count cap gone, the no-signal guard is the
     // vagueness catch-all. The informational risk_level trace entry must not defeat
     // it — only real signals (concerns) count.
-    if (activation.concerns.length === 0 && input.tokenCount >= 4) {
+    if (!declaredSurfaces && activation.concerns.length === 0 && input.tokenCount >= 4) {
         return {
             status: "needs_clarification",
             reasons: [
@@ -2153,7 +2194,22 @@ function prepareCodegenContextCore(raw) {
     if (preGate && preGate.status !== "ready_for_codegen") {
         return blocked(input, raw, preGate.status, preGate.reasons, preGate.suggestions, [], { rejected: [], notes: [] });
     }
-    const activation = activate(input);
+    // 0.20.0-beta.21 — «declarativo primeiro»: por defeito o prepare responde ao
+    // DECLARADO. Sem nenhuma declaração não adivinha a partir do `task`: devolve
+    // needs_input com o vocabulário e a receita (o gateway semântico e o
+    // classificador de intenção vivem no bloco lexical, que aqui não corre).
+    const selectionMode = raw.selection_mode === "discover" ? "discover" : "declarative";
+    const declaredTechnologies = normalizeDeclaredTechnologies(Array.isArray(raw.technologies) ? raw.technologies.filter((t) => typeof t === "string") : [], input.stack);
+    const declarativeSelection = selectionMode !== "discover";
+    const hasDeclaredActivator = input.concerns.length > 0 ||
+        input.exposure !== undefined ||
+        input.data_sensitivity !== undefined ||
+        input.changed_files.length > 0 ||
+        declaredTechnologies.length > 0;
+    // P1-A (0.20.0-beta.22): a decisão de needs_input é UMA e vive no motor — indexada
+    // à activação produzida, não à presença de campos. O prepare reage ao veredicto
+    // (abaixo, depois de correr a selecção), em vez de ter a sua própria regra.
+    const activation = activate(input, { declaredOnly: declarativeSelection });
     // (c) The scope gate measures the request's FOCUS, not its full semantic
     // expansion: explicit concerns when given, else the concerns activated by
     // deterministic sources (explicit input + direct lexicon task terms). Semantic
@@ -2173,7 +2229,22 @@ function prepareCodegenContextCore(raw) {
     void focusConcerns; // kept for the debug notes below; the gate no longer counts requirements
     // MP1 selection (G-mp1a O2): the engine composes baseline ∪ context and narrows
     // by the task's declared signals — this is the requirement set served.
-    const selection = runSelectionWithActivation(input, activation);
+    const selection = runSelectionWithActivation(input, activation, selectionMode === "discover" ? (raw.technologies ?? []) : declaredTechnologies, selectionMode);
+    if (selection.needs_input) {
+        const ni = selection.needs_input;
+        return blocked(input, raw, "needs_input", [
+            ni.reason,
+            "Contrato v1.18-beta: o servidor responde ao declarado e NÃO interpreta o `task` — que fica registado para auditoria."
+        ], [
+            `Lê o vocabulário fechado: read_sbd_toe_resource(uri="${ni.vocabulary_resource}").`,
+            `Re-chama declarando, por exemplo: ${ni.example.with}.`,
+            ...(ni.candidates_to_confirm.from_task_text.length > 0
+                ? [`SUGESTÃO A CONFIRMAR (não é selecção), derivada do texto: [${ni.candidates_to_confirm.from_task_text.join(", ")}] — confirma e declara.`]
+                : []),
+            ...(ni.inert_declarations?.length ? [`Declarações inertes nesta chamada: ${ni.inert_declarations.join("; ")}.`] : []),
+            `Queres o comportamento inferencial antigo? selection_mode="discover" (exploratório).`
+        ], activation.trace);
+    }
     const estimatedRequirements = selection.selected.length;
     // 0.19.4 («a promessa do minimal», lead opção 2): tecto de requisitos por-id
     // por nível de detail, derivado da medição (~68 tk/req min/std, ~29 ultrathin)
@@ -2232,7 +2303,11 @@ function prepareCodegenContextCore(raw) {
     const postGate = gateAfterActivation({
         input,
         activation,
-        estimatedRequirements
+        estimatedRequirements,
+        // Só é "declarado" quando o chamador declarou mesmo: no caminho declarativo a
+        // ausência de declarações já devolveu needs_input antes de chegar aqui, logo
+        // este ponto implica declaração real. Em discover o gate mantém-se inteiro.
+        declaredSurfaces: declarativeSelection && hasDeclaredActivator
     });
     if (postGate && postGate.status !== "ready_for_codegen") {
         return blocked(input, raw, postGate.status, postGate.reasons, postGate.suggestions, activation.trace, { rejected: activation.rejected, notes: activation.notes });