// @bun
// src/components/docs/architecture/ArchitectureKnowledgeBindingPage.tsx
import { CodeBlock } from "@contractspec/lib.design-system";
import Link from "@contractspec/lib.ui-link";
import { ChevronRight } from "lucide-react";
import { jsx, jsxs } from "react/jsx-runtime";
function ArchitectureKnowledgeBindingPage() {
  return /* @__PURE__ */ jsxs("div", {
    className: "space-y-8",
    children: [
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h1", {
            className: "text-4xl font-bold",
            children: "Knowledge Binding"
          }),
          /* @__PURE__ */ jsx("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."
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "How it works"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Knowledge binding follows a three-layer model:"
          }),
          /* @__PURE__ */ jsxs("ol", {
            className: "text-muted-foreground list-inside list-decimal space-y-3",
            children: [
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "KnowledgeSpaceSpec"
                  }),
                  " (global) - Defines a logical knowledge domain"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "KnowledgeSourceConfig"
                  }),
                  " (per-tenant) - Tenant's data sources feeding spaces"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "AppKnowledgeBinding"
                  }),
                  " (per-app) - Maps spaces to workflows/agents"
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Example: Support agent with RAG"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Let's build a support agent that uses canonical product documentation and operational support history."
          }),
          /* @__PURE__ */ jsxs("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsx("h3", {
                className: "text-lg font-semibold",
                children: "Step 1: Blueprint declares knowledge needs"
              }),
              /* @__PURE__ */ jsx(CodeBlock, {
                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"
    }
  ]
}`
              })
            ]
          }),
          /* @__PURE__ */ jsxs("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsx("h3", {
                className: "text-lg font-semibold",
                children: "Step 2: Tenant configures sources"
              }),
              /* @__PURE__ */ jsx(CodeBlock, {
                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"
  }
]`
              })
            ]
          }),
          /* @__PURE__ */ jsxs("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsx("h3", {
                className: "text-lg font-semibold",
                children: "Step 3: TenantAppConfig binds spaces"
              }),
              /* @__PURE__ */ jsx(CodeBlock, {
                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"]
    }
  ]
}`
              })
            ]
          }),
          /* @__PURE__ */ jsxs("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsx("h3", {
                className: "text-lg font-semibold",
                children: "Step 4: Workflow uses knowledge"
              }),
              /* @__PURE__ */ jsx(CodeBlock, {
                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}`
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Category-based access control"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Different knowledge categories have different trust levels and access patterns:"
          }),
          /* @__PURE__ */ jsx("div", {
            className: "border-border/50 overflow-x-auto rounded-lg border",
            children: /* @__PURE__ */ jsxs("table", {
              className: "w-full text-left text-sm",
              children: [
                /* @__PURE__ */ jsx("thead", {
                  className: "bg-card/50",
                  children: /* @__PURE__ */ jsxs("tr", {
                    className: "border-border/50 border-b",
                    children: [
                      /* @__PURE__ */ jsx("th", {
                        className: "px-4 py-3 font-semibold",
                        children: "Category"
                      }),
                      /* @__PURE__ */ jsx("th", {
                        className: "px-4 py-3 font-semibold",
                        children: "Trust Level"
                      }),
                      /* @__PURE__ */ jsx("th", {
                        className: "px-4 py-3 font-semibold",
                        children: "Use Cases"
                      }),
                      /* @__PURE__ */ jsx("th", {
                        className: "px-4 py-3 font-semibold",
                        children: "Policy Impact"
                      })
                    ]
                  })
                }),
                /* @__PURE__ */ jsxs("tbody", {
                  className: "divide-border/50 divide-y",
                  children: [
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 font-mono text-xs",
                          children: "canonical"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Highest"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Product specs, schemas, official policies"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Can drive policy decisions"
                        })
                      ]
                    }),
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 font-mono text-xs",
                          children: "operational"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "High"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Support tickets, sales docs, internal runbooks"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Can inform decisions"
                        })
                      ]
                    }),
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 font-mono text-xs",
                          children: "external"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Medium"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Third-party docs, regulations, PSP guides"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Reference only, not authoritative"
                        })
                      ]
                    }),
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 font-mono text-xs",
                          children: "ephemeral"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Low"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Agent scratchpads, session context, drafts"
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3",
                          children: "Never used for decisions"
                        })
                      ]
                    })
                  ]
                })
              ]
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Multi-space workflows"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Workflows can query multiple knowledge spaces and combine results:"
          }),
          /* @__PURE__ */ jsx(CodeBlock, {
            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"]
  }
]`
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Security & validation"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx("li", {
                children: "Knowledge sources are validated before sync - credentials and permissions checked"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "PDP enforces which workflows/agents can access which spaces"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "All knowledge queries are audited with search terms and results"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Canonical knowledge is immutable once indexed - changes require re-sync"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Ephemeral knowledge is automatically purged based on retention policies"
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Best practices"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx("li", {
                children: "Use canonical spaces for policy-critical decisions, operational for suggestions"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Never allow workflows to write to canonical spaces - maintain read-only access"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Set up monitoring for sync failures and stale knowledge sources"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Document the purpose and trust level of each knowledge space"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Test knowledge queries in sandbox before promoting to production"
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  "Use explicit ",
                  /* @__PURE__ */ jsx("code", {
                    children: "allowedConsumers"
                  }),
                  " - avoid wildcard access"
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "flex items-center gap-4 pt-4",
        children: [
          /* @__PURE__ */ jsx(Link, {
            href: "/docs/architecture/integration-binding",
            className: "btn-ghost",
            children: "Previous: Integration Binding"
          }),
          /* @__PURE__ */ jsxs(Link, {
            href: "/docs/knowledge",
            className: "btn-primary",
            children: [
              "Knowledge & Context ",
              /* @__PURE__ */ jsx(ChevronRight, {
                size: 16
              })
            ]
          })
        ]
      })
    ]
  });
}
export {
  ArchitectureKnowledgeBindingPage
};
