var c=Object.defineProperty;var r=(a)=>a;function l(a,o){this[a]=r.bind(null,o)}var p=(a,o)=>{for(var n in o)c(a,n,{get:o[n],enumerable:!0,configurable:!0,set:l.bind(o,n)})};var u=(a,o)=>()=>(a&&(o=a(a=0)),o);import{CodeBlock as s}from"@contractspec/lib.design-system";import i from"@contractspec/lib.ui-link";import{ChevronRight as d}from"lucide-react";import{jsx as e,jsxs as t}from"react/jsx-runtime";function w(){return t("div",{className:"space-y-8",children:[t("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"Knowledge Binding"}),e("p",{className:"text-muted-foreground",children:"Knowledge binding connects your app's workflows and agents to structured knowledge spaces. This enables semantic search, RAG (Retrieval-Augmented Generation), and context-aware decision-making."})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"How it works"}),e("p",{className:"text-muted-foreground",children:"Knowledge binding follows a three-layer model:"}),t("ol",{className:"list-inside list-decimal space-y-3 text-muted-foreground",children:[t("li",{children:[e("strong",{children:"KnowledgeSpaceSpec"})," (global) - Defines a logical knowledge domain"]}),t("li",{children:[e("strong",{children:"KnowledgeSourceConfig"})," (per-tenant) - Tenant's data sources feeding spaces"]}),t("li",{children:[e("strong",{children:"AppKnowledgeBinding"})," (per-app) - Maps spaces to workflows/agents"]})]})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Example: Support agent with RAG"}),e("p",{className:"text-muted-foreground",children:"Let's build a support agent that uses canonical product documentation and operational support history."}),t("div",{className:"space-y-3",children:[e("h3",{className:"font-semibold text-lg",children:"Step 1: Blueprint declares knowledge needs"}),e(s,{language:"typescript",code:`// AppBlueprintSpec
{
  id: "support-app",
  version: "1.0.0",
  knowledgeSpaces: [
    {
      spaceId: "product-canon",
      category: "canonical",
      required: true,
      purpose: "Official product documentation and specs"
    },
    {
      spaceId: "support-history",
      category: "operational",
      required: true,
      purpose: "Past support tickets and resolutions"
    },
    {
      spaceId: "external-docs",
      category: "external",
      required: false,
      purpose: "Third-party integration documentation"
    }
  ]
}`})]}),t("div",{className:"space-y-3",children:[e("h3",{className:"font-semibold text-lg",children:"Step 2: Tenant configures sources"}),e(s,{language:"typescript",code:`// KnowledgeSourceConfig (per-tenant)
[
  {
    id: "src_notion_product_docs",
    tenantId: "acme-corp",
    spaceId: "product-canon",
    kind: "notion",
    location: "https://notion.so/acme/product-docs",
    syncPolicy: { interval: "1h" },
    lastSyncedAt: "2025-01-15T10:00:00Z"
  },
  {
    id: "src_gmail_support_threads",
    tenantId: "acme-corp",
    spaceId: "support-history",
    kind: "gmail",
    location: "support@acme.com",
    syncPolicy: { webhook: true },
    lastSyncedAt: "2025-01-15T10:30:00Z"
  },
  {
    id: "src_stripe_docs",
    tenantId: "acme-corp",
    spaceId: "external-docs",
    kind: "url",
    location: "https://stripe.com/docs",
    syncPolicy: { interval: "24h" },
    lastSyncedAt: "2025-01-15T00:00:00Z"
  }
]`})]}),t("div",{className:"space-y-3",children:[e("h3",{className:"font-semibold text-lg",children:"Step 3: TenantAppConfig binds spaces"}),e(s,{language:"typescript",code:`// TenantAppConfig
{
  tenantId: "acme-corp",
  blueprintId: "support-app",
  blueprintVersion: "1.0.0",
  knowledgeBindings: [
    {
      spaceId: "product-canon",
      enabled: true,
      allowedConsumers: {
        workflowIds: ["answer-question", "generate-docs"],
        agentIds: ["support-agent", "docs-agent"]
      },
      allowedCategories: ["canonical"],
      sources: ["src_notion_product_docs"]
    },
    {
      spaceId: "support-history",
      enabled: true,
      allowedConsumers: {
        workflowIds: ["answer-question", "escalate-ticket"],
        agentIds: ["support-agent"]
      },
      allowedCategories: ["operational"],
      sources: ["src_gmail_support_threads"]
    },
    {
      spaceId: "external-docs",
      enabled: true,
      allowedConsumers: {
        agentIds: ["support-agent"]
      },
      allowedCategories: ["external"],
      sources: ["src_stripe_docs"]
    }
  ]
}`})]}),t("div",{className:"space-y-3",children:[e("h3",{className:"font-semibold text-lg",children:"Step 4: Workflow uses knowledge"}),e(s,{language:"yaml",code:`// WorkflowSpec
workflowId: answer-question
version: '1.0.0'.0.0

steps:
  - id: generate-embedding
    capability: openai-embeddings
    inputs:
      text: \${input.question}
  
  - id: search-canonical
    capability: vector.search
    inputs:
      collection: "product-canon"
      vector: \${steps.generate-embedding.output.embedding}
      limit: 5
  
  - id: search-support-history
    capability: vector.search
    inputs:
      collection: "support-history"
      vector: \${steps.generate-embedding.output.embedding}
      limit: 3
  
  - id: generate-answer
    capability: openai-chat
    inputs:
      messages:
        - role: "system"
          content: |
            You are a support agent. Answer based on:
            1. Canonical docs (authoritative)
            2. Support history (helpful context)
            Only use external docs for integration questions.
        - role: "user"
          content: |
            Question: \${input.question}
            
            Canonical docs:
            \${steps.search-canonical.output.results}
            
            Support history:
            \${steps.search-support-history.output.results}`})]})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Category-based access control"}),e("p",{className:"text-muted-foreground",children:"Different knowledge categories have different trust levels and access patterns:"}),e("div",{className:"overflow-x-auto rounded-lg border border-border/50",children:t("table",{className:"w-full text-left text-sm",children:[e("thead",{className:"bg-card/50",children:t("tr",{className:"border-border/50 border-b",children:[e("th",{className:"px-4 py-3 font-semibold",children:"Category"}),e("th",{className:"px-4 py-3 font-semibold",children:"Trust Level"}),e("th",{className:"px-4 py-3 font-semibold",children:"Use Cases"}),e("th",{className:"px-4 py-3 font-semibold",children:"Policy Impact"})]})}),t("tbody",{className:"divide-y divide-border/50",children:[t("tr",{children:[e("td",{className:"px-4 py-3 font-mono text-xs",children:"canonical"}),e("td",{className:"px-4 py-3",children:"Highest"}),e("td",{className:"px-4 py-3",children:"Product specs, schemas, official policies"}),e("td",{className:"px-4 py-3",children:"Can drive policy decisions"})]}),t("tr",{children:[e("td",{className:"px-4 py-3 font-mono text-xs",children:"operational"}),e("td",{className:"px-4 py-3",children:"High"}),e("td",{className:"px-4 py-3",children:"Support tickets, sales docs, internal runbooks"}),e("td",{className:"px-4 py-3",children:"Can inform decisions"})]}),t("tr",{children:[e("td",{className:"px-4 py-3 font-mono text-xs",children:"external"}),e("td",{className:"px-4 py-3",children:"Medium"}),e("td",{className:"px-4 py-3",children:"Third-party docs, regulations, PSP guides"}),e("td",{className:"px-4 py-3",children:"Reference only, not authoritative"})]}),t("tr",{children:[e("td",{className:"px-4 py-3 font-mono text-xs",children:"ephemeral"}),e("td",{className:"px-4 py-3",children:"Low"}),e("td",{className:"px-4 py-3",children:"Agent scratchpads, session context, drafts"}),e("td",{className:"px-4 py-3",children:"Never used for decisions"})]})]})]})})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Multi-space workflows"}),e("p",{className:"text-muted-foreground",children:"Workflows can query multiple knowledge spaces and combine results:"}),e(s,{language:"typescript",code:`knowledgeBindings: [
  {
    spaceId: "product-canon",
    enabled: true,
    allowedConsumers: {
      workflowIds: ["invoice-generation", "quote-creation"]
    },
    allowedCategories: ["canonical"],
    sources: ["src_database_schema", "src_product_catalog"]
  },
  {
    spaceId: "pricing-rules",
    enabled: true,
    allowedConsumers: {
      workflowIds: ["invoice-generation", "quote-creation"]
    },
    allowedCategories: ["canonical", "operational"],
    sources: ["src_pricing_database", "src_discount_policies"]
  },
  {
    spaceId: "customer-history",
    enabled: true,
    allowedConsumers: {
      workflowIds: ["quote-creation"]
    },
    allowedCategories: ["operational"],
    sources: ["src_crm_data", "src_past_invoices"]
  }
]`})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Security & validation"}),t("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[e("li",{children:"Knowledge sources are validated before sync - credentials and permissions checked"}),e("li",{children:"PDP enforces which workflows/agents can access which spaces"}),e("li",{children:"All knowledge queries are audited with search terms and results"}),e("li",{children:"Canonical knowledge is immutable once indexed - changes require re-sync"}),e("li",{children:"Ephemeral knowledge is automatically purged based on retention policies"})]})]}),t("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Best practices"}),t("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[e("li",{children:"Use canonical spaces for policy-critical decisions, operational for suggestions"}),e("li",{children:"Never allow workflows to write to canonical spaces - maintain read-only access"}),e("li",{children:"Set up monitoring for sync failures and stale knowledge sources"}),e("li",{children:"Document the purpose and trust level of each knowledge space"}),e("li",{children:"Test knowledge queries in sandbox before promoting to production"}),t("li",{children:["Use explicit ",e("code",{children:"allowedConsumers"})," - avoid wildcard access"]})]})]}),t("div",{className:"flex items-center gap-4 pt-4",children:[e(i,{href:"/docs/architecture/integration-binding",className:"btn-ghost",children:"Previous: Integration Binding"}),t(i,{href:"/docs/knowledge",className:"btn-primary",children:["Knowledge & Context ",e(d,{size:16})]})]})]})}export{w as ArchitectureKnowledgeBindingPage};
