@contractspec/lib.knowledge 2.4.0 → 2.5.0

package/dist/access/guard.d.ts

@@ -5,11 +5,14 @@ export interface KnowledgeAccessGuardOptions {
     disallowWriteCategories?: KnowledgeCategory[];
     requireWorkflowBinding?: boolean;
     requireAgentBinding?: boolean;
+    /** Default locale for access denial/warning messages */
+    locale?: string;
 }
 export declare class KnowledgeAccessGuard {
     private readonly disallowedWrite;
     private readonly requireWorkflowBinding;
     private readonly requireAgentBinding;
+    private readonly i18n;
     constructor(options?: KnowledgeAccessGuardOptions);
     checkAccess(spaceBinding: ResolvedKnowledge, context: KnowledgeAccessContext, appConfig: ResolvedAppConfig): KnowledgeAccessResult;
     private isSpaceBound;

package/dist/access/guard.js

@@ -1,4 +1,274 @@
 // @bun
+// src/i18n/catalogs/en.ts
+import { defineTranslation } from "@contractspec/lib.contracts-spec/translations";
+var enMessages = defineTranslation({
+  meta: {
+    key: "knowledge.messages",
+    version: "1.0.0",
+    domain: "knowledge",
+    description: "All user-facing and LLM-facing strings for the knowledge package",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "en",
+  fallback: "en",
+  messages: {
+    "access.notBound": {
+      value: 'Knowledge space "{spaceKey}" is not bound in the resolved app config.',
+      description: "Denial reason when a knowledge space is not bound",
+      placeholders: [{ name: "spaceKey", type: "string" }]
+    },
+    "access.readOnly": {
+      value: 'Knowledge space "{spaceKey}" is category "{category}" and is read-only.',
+      description: "Denial reason when write is attempted on a read-only space",
+      placeholders: [
+        { name: "spaceKey", type: "string" },
+        { name: "category", type: "string" }
+      ]
+    },
+    "access.workflowUnauthorized": {
+      value: 'Workflow "{workflowName}" is not authorized to access knowledge space "{spaceKey}".',
+      description: "Denial reason when a workflow lacks space access",
+      placeholders: [
+        { name: "workflowName", type: "string" },
+        { name: "spaceKey", type: "string" }
+      ]
+    },
+    "access.agentUnauthorized": {
+      value: 'Agent "{agentName}" is not authorized to access knowledge space "{spaceKey}".',
+      description: "Denial reason when an agent lacks space access",
+      placeholders: [
+        { name: "agentName", type: "string" },
+        { name: "spaceKey", type: "string" }
+      ]
+    },
+    "access.ephemeralWarning": {
+      value: 'Knowledge space "{spaceKey}" is ephemeral; results may be transient.',
+      description: "Warning for ephemeral knowledge spaces",
+      placeholders: [{ name: "spaceKey", type: "string" }]
+    },
+    "query.systemPrompt": {
+      value: "You are a knowledge assistant that answers questions using the provided context. Cite relevant sources if possible.",
+      description: "Default LLM system prompt for knowledge queries"
+    },
+    "query.userMessage": {
+      value: `Question:
+{question}
+
+Context:
+{context}`,
+      description: "User message template combining question and context",
+      placeholders: [
+        { name: "question", type: "string" },
+        { name: "context", type: "string" }
+      ]
+    },
+    "query.noResults": {
+      value: "No relevant documents found.",
+      description: "Displayed when vector search returns zero results"
+    },
+    "query.sourceLabel": {
+      value: "Source {index} (score: {score}):",
+      description: "Label prefix for each source in the context block",
+      placeholders: [
+        { name: "index", type: "number" },
+        { name: "score", type: "string" }
+      ]
+    },
+    "ingestion.gmail.subject": {
+      value: "Subject: {subject}",
+      description: "Gmail thread subject label",
+      placeholders: [{ name: "subject", type: "string" }]
+    },
+    "ingestion.gmail.snippet": {
+      value: "Snippet: {snippet}",
+      description: "Gmail thread snippet label",
+      placeholders: [{ name: "snippet", type: "string" }]
+    },
+    "ingestion.gmail.from": {
+      value: "From: {from}",
+      description: "Gmail message sender label",
+      placeholders: [{ name: "from", type: "string" }]
+    },
+    "ingestion.gmail.to": {
+      value: "To: {to}",
+      description: "Gmail message recipients label",
+      placeholders: [{ name: "to", type: "string" }]
+    },
+    "ingestion.gmail.date": {
+      value: "Date: {date}",
+      description: "Gmail message date label",
+      placeholders: [{ name: "date", type: "string" }]
+    }
+  }
+});
+
+// src/i18n/catalogs/fr.ts
+import { defineTranslation as defineTranslation2 } from "@contractspec/lib.contracts-spec/translations";
+var frMessages = defineTranslation2({
+  meta: {
+    key: "knowledge.messages",
+    version: "1.0.0",
+    domain: "knowledge",
+    description: "All user-facing and LLM-facing strings for the knowledge package (French)",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "fr",
+  fallback: "en",
+  messages: {
+    "access.notBound": {
+      value: `L'espace de connaissances "{spaceKey}" n'est pas li\xE9 dans la configuration de l'application.`,
+      description: "Denial reason when a knowledge space is not bound"
+    },
+    "access.readOnly": {
+      value: `L'espace de connaissances "{spaceKey}" est de cat\xE9gorie "{category}" et est en lecture seule.`,
+      description: "Denial reason when write is attempted on a read-only space"
+    },
+    "access.workflowUnauthorized": {
+      value: `Le workflow "{workflowName}" n'est pas autoris\xE9 \xE0 acc\xE9der \xE0 l'espace de connaissances "{spaceKey}".`,
+      description: "Denial reason when a workflow lacks space access"
+    },
+    "access.agentUnauthorized": {
+      value: `L'agent "{agentName}" n'est pas autoris\xE9 \xE0 acc\xE9der \xE0 l'espace de connaissances "{spaceKey}".`,
+      description: "Denial reason when an agent lacks space access"
+    },
+    "access.ephemeralWarning": {
+      value: `L'espace de connaissances "{spaceKey}" est \xE9ph\xE9m\xE8re ; les r\xE9sultats peuvent \xEAtre transitoires.`,
+      description: "Warning for ephemeral knowledge spaces"
+    },
+    "query.systemPrompt": {
+      value: "Vous \xEAtes un assistant de connaissances qui r\xE9pond aux questions en utilisant le contexte fourni. Citez les sources pertinentes si possible.",
+      description: "Default LLM system prompt for knowledge queries"
+    },
+    "query.userMessage": {
+      value: `Question :
+{question}
+
+Contexte :
+{context}`,
+      description: "User message template combining question and context"
+    },
+    "query.noResults": {
+      value: "Aucun document pertinent trouv\xE9.",
+      description: "Displayed when vector search returns zero results"
+    },
+    "query.sourceLabel": {
+      value: "Source {index} (score : {score}) :",
+      description: "Label prefix for each source in the context block"
+    },
+    "ingestion.gmail.subject": {
+      value: "Objet : {subject}",
+      description: "Gmail thread subject label"
+    },
+    "ingestion.gmail.snippet": {
+      value: "Extrait : {snippet}",
+      description: "Gmail thread snippet label"
+    },
+    "ingestion.gmail.from": {
+      value: "De : {from}",
+      description: "Gmail message sender label"
+    },
+    "ingestion.gmail.to": {
+      value: "\xC0 : {to}",
+      description: "Gmail message recipients label"
+    },
+    "ingestion.gmail.date": {
+      value: "Date : {date}",
+      description: "Gmail message date label"
+    }
+  }
+});
+
+// src/i18n/catalogs/es.ts
+import { defineTranslation as defineTranslation3 } from "@contractspec/lib.contracts-spec/translations";
+var esMessages = defineTranslation3({
+  meta: {
+    key: "knowledge.messages",
+    version: "1.0.0",
+    domain: "knowledge",
+    description: "All user-facing and LLM-facing strings for the knowledge package (Spanish)",
+    owners: ["platform"],
+    stability: "experimental"
+  },
+  locale: "es",
+  fallback: "en",
+  messages: {
+    "access.notBound": {
+      value: 'El espacio de conocimiento "{spaceKey}" no est\xE1 vinculado en la configuraci\xF3n de la aplicaci\xF3n.',
+      description: "Denial reason when a knowledge space is not bound"
+    },
+    "access.readOnly": {
+      value: 'El espacio de conocimiento "{spaceKey}" es de categor\xEDa "{category}" y es de solo lectura.',
+      description: "Denial reason when write is attempted on a read-only space"
+    },
+    "access.workflowUnauthorized": {
+      value: 'El flujo de trabajo "{workflowName}" no est\xE1 autorizado para acceder al espacio de conocimiento "{spaceKey}".',
+      description: "Denial reason when a workflow lacks space access"
+    },
+    "access.agentUnauthorized": {
+      value: 'El agente "{agentName}" no est\xE1 autorizado para acceder al espacio de conocimiento "{spaceKey}".',
+      description: "Denial reason when an agent lacks space access"
+    },
+    "access.ephemeralWarning": {
+      value: 'El espacio de conocimiento "{spaceKey}" es ef\xEDmero; los resultados pueden ser transitorios.',
+      description: "Warning for ephemeral knowledge spaces"
+    },
+    "query.systemPrompt": {
+      value: "Eres un asistente de conocimiento que responde preguntas utilizando el contexto proporcionado. Cita las fuentes relevantes si es posible.",
+      description: "Default LLM system prompt for knowledge queries"
+    },
+    "query.userMessage": {
+      value: `Pregunta:
+{question}
+
+Contexto:
+{context}`,
+      description: "User message template combining question and context"
+    },
+    "query.noResults": {
+      value: "No se encontraron documentos relevantes.",
+      description: "Displayed when vector search returns zero results"
+    },
+    "query.sourceLabel": {
+      value: "Fuente {index} (puntuaci\xF3n: {score}):",
+      description: "Label prefix for each source in the context block"
+    },
+    "ingestion.gmail.subject": {
+      value: "Asunto: {subject}",
+      description: "Gmail thread subject label"
+    },
+    "ingestion.gmail.snippet": {
+      value: "Extracto: {snippet}",
+      description: "Gmail thread snippet label"
+    },
+    "ingestion.gmail.from": {
+      value: "De: {from}",
+      description: "Gmail message sender label"
+    },
+    "ingestion.gmail.to": {
+      value: "Para: {to}",
+      description: "Gmail message recipients label"
+    },
+    "ingestion.gmail.date": {
+      value: "Fecha: {date}",
+      description: "Gmail message date label"
+    }
+  }
+});
+
+// src/i18n/messages.ts
+import {
+  createI18nFactory
+} from "@contractspec/lib.contracts-spec/translations";
+var factory = createI18nFactory({
+  specKey: "knowledge.messages",
+  catalogs: [enMessages, frMessages, esMessages]
+});
+var createKnowledgeI18n = factory.create;
+var getDefaultI18n = factory.getDefault;
+var resetI18nRegistry = factory.resetRegistry;
+
 // src/access/guard.ts
 var DEFAULT_DISALLOWED_WRITE = ["external", "ephemeral"];
 
@@ -6,23 +276,30 @@ class KnowledgeAccessGuard {
   disallowedWrite;
   requireWorkflowBinding;
   requireAgentBinding;
+  i18n;
   constructor(options = {}) {
     this.disallowedWrite = new Set(options.disallowWriteCategories ?? DEFAULT_DISALLOWED_WRITE);
     this.requireWorkflowBinding = options.requireWorkflowBinding ?? true;
     this.requireAgentBinding = options.requireAgentBinding ?? false;
+    this.i18n = options.locale ? createKnowledgeI18n(options.locale) : getDefaultI18n();
   }
   checkAccess(spaceBinding, context, appConfig) {
     const { binding, space } = spaceBinding;
     if (binding.required !== false && !this.isSpaceBound(spaceBinding, appConfig)) {
       return {
         allowed: false,
-        reason: `Knowledge space "${space.meta.key}" is not bound in the resolved app config.`
+        reason: this.i18n.t("access.notBound", {
+          spaceKey: space.meta.key
+        })
       };
     }
     if (context.operation === "write" && this.disallowedWrite.has(space.meta.category)) {
       return {
         allowed: false,
-        reason: `Knowledge space "${space.meta.key}" is category "${space.meta.category}" and is read-only.`
+        reason: this.i18n.t("access.readOnly", {
+          spaceKey: space.meta.key,
+          category: space.meta.category
+        })
       };
     }
     if (this.requireWorkflowBinding && context.workflowName) {
@@ -30,7 +307,10 @@ class KnowledgeAccessGuard {
       if (allowedWorkflows && !allowedWorkflows.includes(context.workflowName)) {
         return {
           allowed: false,
-          reason: `Workflow "${context.workflowName}" is not authorized to access knowledge space "${space.meta.key}".`
+          reason: this.i18n.t("access.workflowUnauthorized", {
+            workflowName: context.workflowName,
+            spaceKey: space.meta.key
+          })
         };
       }
     }
@@ -39,7 +319,10 @@ class KnowledgeAccessGuard {
       if (allowedAgents && !allowedAgents.includes(context.agentName)) {
         return {
           allowed: false,
-          reason: `Agent "${context.agentName}" is not authorized to access knowledge space "${space.meta.key}".`
+          reason: this.i18n.t("access.agentUnauthorized", {
+            agentName: context.agentName,
+            spaceKey: space.meta.key
+          })
         };
       }
     }
@@ -47,7 +330,9 @@ class KnowledgeAccessGuard {
       return {
         allowed: true,
         severity: "warning",
-        reason: `Knowledge space "${space.meta.key}" is ephemeral; results may be transient.`
+        reason: this.i18n.t("access.ephemeralWarning", {
+          spaceKey: space.meta.key
+        })
       };
     }
     return { allowed: true };