@contractspec/example.policy-safe-knowledge-assistant 1.56.1 → 1.58.0

package/dist/index.js

@@ -1,10 +1,918 @@
-import example_default from "./example.js";
-import { PolicySafeKnowledgeAssistantFeature } from "./policy-safe-knowledge-assistant.feature.js";
-import { DEMO_FIXTURES } from "./seed/fixtures.js";
-import { buildPolicySafeAnswer } from "./orchestrator/buildAnswer.js";
-import { createPolicySafeKnowledgeAssistantHandlers } from "./handlers/policy-safe-knowledge-assistant.handlers.js";
-import { PolicySafeKnowledgeAssistantDashboard } from "./ui/PolicySafeKnowledgeAssistantDashboard.js";
-import "./ui/index.js";
-import "./docs/index.js";
-
-export { DEMO_FIXTURES, PolicySafeKnowledgeAssistantDashboard, PolicySafeKnowledgeAssistantFeature, buildPolicySafeAnswer, createPolicySafeKnowledgeAssistantHandlers, example_default as example };
+// @bun
+// src/docs/policy-safe-knowledge-assistant.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var docBlocks = [
+  {
+    id: "docs.examples.policy-safe-knowledge-assistant.goal",
+    title: "Policy-safe Knowledge Assistant \u2014 Goal",
+    summary: "End-to-end example: versioned KB snapshots + locale/jurisdiction gating + HITL pipeline + learning hub.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/policy-safe-knowledge-assistant/goal",
+    tags: ["assistant", "knowledge", "policy", "hitl", "learning"],
+    body: `## What this template proves
+- Assistant answers are structured and must cite a KB snapshot (or refuse).
+- Locale + jurisdiction are mandatory inputs for every assistant call.
+- Automation proposes KB patches; humans verify; publishing stays blocked until approvals.
+- Learning hub demonstrates drills + coaching + quests without spam.
+
+## Offline-first
+- Seeded fixtures are deterministic and require no external services.
+- Optional non-authoritative fallback can be added behind a single feature flag (disabled by default).`
+  },
+  {
+    id: "docs.examples.policy-safe-knowledge-assistant.usage",
+    title: "Policy-safe Knowledge Assistant \u2014 Usage",
+    summary: "5\u201310 minute sandbox walkthrough for developers.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/policy-safe-knowledge-assistant/usage",
+    tags: ["assistant", "knowledge", "usage"],
+    body: `## Demo walkthrough (high level)
+1) Onboard: set locale + jurisdiction.
+2) Publish snapshot: ingest source -> propose rule -> approve -> publish.
+3) Ask assistant: must pass gate and cite snapshot.
+4) Simulate change: watcher -> review -> publish new snapshot.
+5) Learning hub: drills session, ambient tip, quest start + step completion.`
+  }
+];
+registerDocBlocks(docBlocks);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var example = defineExample({
+  meta: {
+    key: "policy-safe-knowledge-assistant",
+    version: "1.0.0",
+    title: "Policy-safe Knowledge Assistant",
+    description: "All-in-one template: locale/jurisdiction gating + versioned KB snapshots + HITL update pipeline + learning hub.",
+    kind: "template",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.core"],
+    tags: ["assistant", "knowledge", "policy", "hitl", "learning"]
+  },
+  docs: {
+    goalDocId: "docs.examples.policy-safe-knowledge-assistant.goal",
+    usageDocId: "docs.examples.policy-safe-knowledge-assistant.usage"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.policy-safe-knowledge-assistant",
+    feature: "./policy-safe-knowledge-assistant.feature",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: {
+      enabled: true,
+      modes: ["playground", "specs", "builder", "markdown", "evolution"]
+    },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+
+// src/orchestrator/buildAnswer.ts
+import {
+  enforceAllowedScope,
+  enforceCitations,
+  validateEnvelope
+} from "@contractspec/example.locale-jurisdiction-gate/policy/guard";
+async function buildPolicySafeAnswer(input) {
+  const env = validateEnvelope(input.envelope);
+  if (!env.ok) {
+    return {
+      locale: input.envelope.locale ?? "en-GB",
+      jurisdiction: input.envelope.regulatoryContext?.jurisdiction ?? "UNKNOWN",
+      allowedScope: input.envelope.allowedScope ?? "education_only",
+      sections: [{ heading: "Request blocked", body: env.error.message }],
+      citations: [],
+      disclaimers: ["This system refuses to answer without a valid envelope."],
+      riskFlags: [env.error.code],
+      refused: true,
+      refusalReason: env.error.code
+    };
+  }
+  const results = await input.kbSearch({
+    snapshotId: env.value.kbSnapshotId,
+    jurisdiction: env.value.regulatoryContext?.jurisdiction ?? "UNKNOWN",
+    query: input.question
+  });
+  const citations = results.items.map((item) => ({
+    kbSnapshotId: env.value.kbSnapshotId,
+    sourceType: "ruleVersion",
+    sourceId: item.ruleVersionId,
+    title: "Curated rule version",
+    excerpt: item.excerpt
+  }));
+  const draft = {
+    locale: env.value.locale,
+    jurisdiction: env.value.regulatoryContext?.jurisdiction ?? "UNKNOWN",
+    allowedScope: env.value.allowedScope,
+    sections: [
+      {
+        heading: "Answer (KB-derived)",
+        body: results.items.length > 0 ? `This answer is derived from ${results.items.length} curated rule version(s) in the referenced snapshot.` : "No curated knowledge found in the referenced snapshot."
+      }
+    ],
+    citations,
+    disclaimers: ["Educational demo only."],
+    riskFlags: []
+  };
+  const scope = enforceAllowedScope(env.value.allowedScope, draft);
+  if (!scope.ok) {
+    return {
+      ...draft,
+      sections: [{ heading: "Escalation required", body: scope.error.message }],
+      refused: true,
+      refusalReason: scope.error.code,
+      riskFlags: [...draft.riskFlags ?? [], scope.error.code]
+    };
+  }
+  const cited = enforceCitations(draft);
+  if (!cited.ok) {
+    return {
+      ...draft,
+      sections: [{ heading: "Request blocked", body: cited.error.message }],
+      citations: [],
+      refused: true,
+      refusalReason: cited.error.code,
+      riskFlags: [...draft.riskFlags ?? [], cited.error.code]
+    };
+  }
+  return draft;
+}
+
+// src/handlers/policy-safe-knowledge-assistant.handlers.ts
+import { web } from "@contractspec/lib.runtime-sandbox";
+var { generateId } = web;
+function parseJsonArray(value) {
+  if (!value)
+    return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.filter((v) => typeof v === "string") : [];
+  } catch {
+    return [];
+  }
+}
+function nowIso() {
+  return new Date().toISOString();
+}
+function createPolicySafeKnowledgeAssistantHandlers(db) {
+  async function getUserContext(input) {
+    const result = await db.query(`SELECT * FROM psa_user_context WHERE "projectId" = $1 LIMIT 1`, [input.projectId]);
+    const row = result.rows[0];
+    if (!row) {
+      return {
+        projectId: input.projectId,
+        locale: "en-GB",
+        jurisdiction: "EU",
+        allowedScope: "education_only",
+        kbSnapshotId: null
+      };
+    }
+    return {
+      projectId: row.projectId,
+      locale: row.locale,
+      jurisdiction: row.jurisdiction,
+      allowedScope: row.allowedScope,
+      kbSnapshotId: row.kbSnapshotId
+    };
+  }
+  async function setUserContext(input) {
+    const existing = await db.query(`SELECT "projectId" FROM psa_user_context WHERE "projectId" = $1 LIMIT 1`, [input.projectId]);
+    if (existing.rows.length) {
+      await db.execute(`UPDATE psa_user_context SET locale = $1, jurisdiction = $2, "allowedScope" = $3 WHERE "projectId" = $4`, [input.locale, input.jurisdiction, input.allowedScope, input.projectId]);
+    } else {
+      await db.execute(`INSERT INTO psa_user_context ("projectId", locale, jurisdiction, "allowedScope", "kbSnapshotId") VALUES ($1, $2, $3, $4, $5)`, [
+        input.projectId,
+        input.locale,
+        input.jurisdiction,
+        input.allowedScope,
+        null
+      ]);
+    }
+    return await getUserContext({ projectId: input.projectId });
+  }
+  async function createRule(input) {
+    const id = generateId("psa_rule");
+    await db.execute(`INSERT INTO psa_rule (id, "projectId", jurisdiction, "topicKey") VALUES ($1, $2, $3, $4)`, [id, input.projectId, input.jurisdiction, input.topicKey]);
+    return { id, ...input };
+  }
+  async function upsertRuleVersion(input) {
+    if (!input.sourceRefs.length)
+      throw new Error("SOURCE_REFS_REQUIRED");
+    const rulesResult = await db.query(`SELECT * FROM psa_rule WHERE id = $1 LIMIT 1`, [input.ruleId]);
+    const rule = rulesResult.rows[0];
+    if (!rule)
+      throw new Error("RULE_NOT_FOUND");
+    const maxResult = await db.query(`SELECT MAX(version) as maxVersion FROM psa_rule_version WHERE "ruleId" = $1`, [input.ruleId]);
+    const maxVersion = Number(maxResult.rows[0]?.maxVersion ?? 0);
+    const version = maxVersion + 1;
+    const id = generateId("psa_rv");
+    const createdAt = nowIso();
+    await db.execute(`INSERT INTO psa_rule_version (id, "ruleId", jurisdiction, "topicKey", version, content, status, "sourceRefsJson", "approvedBy", "approvedAt", "createdAt")
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`, [
+      id,
+      input.ruleId,
+      rule.jurisdiction,
+      rule.topicKey,
+      version,
+      input.content,
+      "draft",
+      JSON.stringify(input.sourceRefs),
+      null,
+      null,
+      createdAt
+    ]);
+    return {
+      id,
+      ruleId: input.ruleId,
+      jurisdiction: rule.jurisdiction,
+      topicKey: rule.topicKey,
+      version,
+      content: input.content,
+      status: "draft",
+      sourceRefs: input.sourceRefs,
+      createdAt: new Date(createdAt)
+    };
+  }
+  async function approveRuleVersion(input) {
+    const approvedAt = nowIso();
+    await db.execute(`UPDATE psa_rule_version SET status = $1, "approvedBy" = $2, "approvedAt" = $3 WHERE id = $4`, ["approved", input.approver, approvedAt, input.ruleVersionId]);
+    return { ruleVersionId: input.ruleVersionId, status: "approved" };
+  }
+  async function publishSnapshot(input) {
+    const approvedResult = await db.query(`SELECT id FROM psa_rule_version WHERE jurisdiction = $1 AND status = 'approved' ORDER BY id ASC`, [input.jurisdiction]);
+    const includedIds = approvedResult.rows.map((r) => r.id).filter(Boolean);
+    if (!includedIds.length)
+      throw new Error("NO_APPROVED_RULES");
+    const id = generateId("psa_snap");
+    const publishedAt = nowIso();
+    await db.execute(`INSERT INTO psa_snapshot (id, jurisdiction, "asOfDate", "includedRuleVersionIdsJson", "publishedAt")
+       VALUES ($1, $2, $3, $4, $5)`, [
+      id,
+      input.jurisdiction,
+      input.asOfDate.toISOString(),
+      JSON.stringify(includedIds),
+      publishedAt
+    ]);
+    await db.execute(`UPDATE psa_user_context SET "kbSnapshotId" = $1 WHERE "projectId" = $2`, [id, input.projectId]);
+    return {
+      id,
+      jurisdiction: input.jurisdiction,
+      includedRuleVersionIds: includedIds
+    };
+  }
+  async function searchKb(input) {
+    const snapResult = await db.query(`SELECT * FROM psa_snapshot WHERE id = $1 LIMIT 1`, [input.snapshotId]);
+    const snap = snapResult.rows[0];
+    if (!snap)
+      throw new Error("SNAPSHOT_NOT_FOUND");
+    if (snap.jurisdiction !== input.jurisdiction)
+      throw new Error("JURISDICTION_MISMATCH");
+    const includedIds = parseJsonArray(snap.includedRuleVersionIdsJson);
+    const tokens = input.query.toLowerCase().split(/\s+/).map((t) => t.trim()).filter(Boolean);
+    const items = [];
+    for (const id of includedIds) {
+      const rvResult = await db.query(`SELECT * FROM psa_rule_version WHERE id = $1 LIMIT 1`, [id]);
+      const rv = rvResult.rows[0];
+      if (!rv)
+        continue;
+      const hay = rv.content.toLowerCase();
+      const match = tokens.length ? tokens.every((t) => hay.includes(t)) : true;
+      if (!match)
+        continue;
+      items.push({ ruleVersionId: rv.id, excerpt: rv.content.slice(0, 140) });
+    }
+    return { items };
+  }
+  async function answer(input) {
+    const ctx = await getUserContext({ projectId: input.projectId });
+    if (!ctx.kbSnapshotId) {
+      const refused = await buildPolicySafeAnswer({
+        envelope: {
+          traceId: generateId("trace"),
+          locale: ctx.locale,
+          kbSnapshotId: "",
+          allowedScope: ctx.allowedScope,
+          regulatoryContext: { jurisdiction: ctx.jurisdiction }
+        },
+        question: input.question,
+        kbSearch: async () => ({ items: [] })
+      });
+      return refused;
+    }
+    return await buildPolicySafeAnswer({
+      envelope: {
+        traceId: generateId("trace"),
+        locale: ctx.locale,
+        kbSnapshotId: ctx.kbSnapshotId,
+        allowedScope: ctx.allowedScope,
+        regulatoryContext: { jurisdiction: ctx.jurisdiction }
+      },
+      question: input.question,
+      kbSearch: async (q) => await searchKb(q)
+    });
+  }
+  async function createChangeCandidate(input) {
+    const id = generateId("psa_change");
+    await db.execute(`INSERT INTO psa_change_candidate (id, "projectId", jurisdiction, "detectedAt", "diffSummary", "riskLevel", "proposedRuleVersionIdsJson")
+       VALUES ($1, $2, $3, $4, $5, $6, $7)`, [
+      id,
+      input.projectId,
+      input.jurisdiction,
+      nowIso(),
+      input.diffSummary,
+      input.riskLevel,
+      JSON.stringify(input.proposedRuleVersionIds)
+    ]);
+    return { id };
+  }
+  async function createReviewTask(input) {
+    const candResult = await db.query(`SELECT * FROM psa_change_candidate WHERE id = $1 LIMIT 1`, [input.changeCandidateId]);
+    const candidate = candResult.rows[0];
+    if (!candidate)
+      throw new Error("CHANGE_CANDIDATE_NOT_FOUND");
+    const assignedRole = candidate.riskLevel === "high" ? "expert" : "curator";
+    const id = generateId("psa_review");
+    await db.execute(`INSERT INTO psa_review_task (id, "changeCandidateId", status, "assignedRole", decision, "decidedAt", "decidedBy")
+       VALUES ($1, $2, $3, $4, $5, $6, $7)`, [id, input.changeCandidateId, "open", assignedRole, null, null, null]);
+    return { id, assignedRole };
+  }
+  async function submitDecision(input) {
+    const reviewResult = await db.query(`SELECT * FROM psa_review_task WHERE id = $1 LIMIT 1`, [input.reviewTaskId]);
+    const task = reviewResult.rows[0];
+    if (!task)
+      throw new Error("REVIEW_TASK_NOT_FOUND");
+    const candidateResult = await db.query(`SELECT * FROM psa_change_candidate WHERE id = $1 LIMIT 1`, [task.changeCandidateId]);
+    const candidate = candidateResult.rows[0];
+    if (!candidate)
+      throw new Error("CHANGE_CANDIDATE_NOT_FOUND");
+    if (candidate.riskLevel === "high" && input.decision === "approve" && input.decidedByRole !== "expert") {
+      throw new Error("FORBIDDEN_ROLE");
+    }
+    const decidedAt = nowIso();
+    await db.execute(`UPDATE psa_review_task SET status = $1, decision = $2, "decidedAt" = $3, "decidedBy" = $4 WHERE id = $5`, [
+      "decided",
+      input.decision,
+      decidedAt,
+      input.decidedBy,
+      input.reviewTaskId
+    ]);
+    return { id: input.reviewTaskId, status: "decided" };
+  }
+  async function publishIfReady(input) {
+    const openResult = await db.query(`SELECT COUNT(*) as count FROM psa_review_task WHERE status != 'decided'`, []);
+    const openCount = Number(openResult.rows[0]?.count ?? 0);
+    if (openCount > 0)
+      throw new Error("NOT_READY");
+    const decidedResult = await db.query(`SELECT * FROM psa_review_task`, []);
+    for (const row of decidedResult.rows) {
+      if (row.decision !== "approve")
+        continue;
+      const candQueryResult = await db.query(`SELECT * FROM psa_change_candidate WHERE id = $1 LIMIT 1`, [row.changeCandidateId]);
+      const cand = candQueryResult.rows[0];
+      if (!cand)
+        continue;
+      if (cand.jurisdiction !== input.jurisdiction)
+        continue;
+      const proposedIds = parseJsonArray(cand.proposedRuleVersionIdsJson);
+      for (const rvId of proposedIds) {
+        const rvQueryResult = await db.query(`SELECT status FROM psa_rule_version WHERE id = $1 LIMIT 1`, [rvId]);
+        const status = String(rvQueryResult.rows[0]?.status ?? "");
+        if (status !== "approved")
+          throw new Error("NOT_READY");
+      }
+    }
+    return { published: true };
+  }
+  return {
+    getUserContext,
+    setUserContext,
+    createRule,
+    upsertRuleVersion,
+    approveRuleVersion,
+    publishSnapshot,
+    searchKb,
+    answer,
+    createChangeCandidate,
+    createReviewTask,
+    submitDecision,
+    publishIfReady
+  };
+}
+
+// src/policy-safe-knowledge-assistant.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var PolicySafeKnowledgeAssistantFeature = defineFeature({
+  meta: {
+    key: "policy-safe-knowledge-assistant",
+    version: "1.0.0",
+    title: "Policy-safe Knowledge Assistant",
+    description: "All-in-one example composing locale/jurisdiction gate + versioned KB + HITL pipeline + learning hub.",
+    domain: "knowledge",
+    owners: ["@examples"],
+    tags: ["assistant", "knowledge", "policy", "hitl", "learning"],
+    stability: "experimental"
+  },
+  operations: [
+    { key: "assistant.answer", version: "1.0.0" },
+    { key: "assistant.explainConcept", version: "1.0.0" },
+    { key: "kb.ingestSource", version: "1.0.0" },
+    { key: "kb.upsertRuleVersion", version: "1.0.0" },
+    { key: "kb.approveRuleVersion", version: "1.0.0" },
+    { key: "kb.publishSnapshot", version: "1.0.0" },
+    { key: "kb.search", version: "1.0.0" },
+    { key: "kbPipeline.runWatch", version: "1.0.0" },
+    { key: "kbPipeline.createReviewTask", version: "1.0.0" },
+    { key: "kbPipeline.submitDecision", version: "1.0.0" },
+    { key: "kbPipeline.publishIfReady", version: "1.0.0" }
+  ],
+  events: [
+    { key: "assistant.answer.requested", version: "1.0.0" },
+    { key: "assistant.answer.blocked", version: "1.0.0" },
+    { key: "assistant.answer.delivered", version: "1.0.0" },
+    { key: "kb.source.ingested", version: "1.0.0" },
+    { key: "kb.ruleVersion.created", version: "1.0.0" },
+    { key: "kb.ruleVersion.approved", version: "1.0.0" },
+    { key: "kb.snapshot.published", version: "1.0.0" },
+    { key: "kb.change.detected", version: "1.0.0" },
+    { key: "kb.review.requested", version: "1.0.0" },
+    { key: "kb.review.decided", version: "1.0.0" }
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    requires: [
+      { key: "identity", version: "1.0.0" },
+      { key: "audit-trail", version: "1.0.0" },
+      { key: "notifications", version: "1.0.0" },
+      { key: "jobs", version: "1.0.0" },
+      { key: "feature-flags", version: "1.0.0" },
+      { key: "files", version: "1.0.0" },
+      { key: "metering", version: "1.0.0" },
+      { key: "learning-journey", version: "1.0.0" }
+    ]
+  }
+});
+
+// src/seed/fixtures.ts
+var DEMO_FIXTURES = {
+  jurisdictions: ["EU", "FR"],
+  locales: ["en-GB", "fr-FR"],
+  demoOrgId: "org_demo",
+  demoUserId: "user_demo",
+  sources: {
+    EU_SOURCE_1: {
+      jurisdiction: "EU",
+      authority: "DemoAuthority",
+      title: "EU Demo Source v1",
+      fetchedAt: new Date("2026-01-01T00:00:00.000Z"),
+      hash: "hash_eu_v1",
+      fileId: "file_eu_v1"
+    },
+    EU_SOURCE_2: {
+      jurisdiction: "EU",
+      authority: "DemoAuthority",
+      title: "EU Demo Source v2",
+      fetchedAt: new Date("2026-02-01T00:00:00.000Z"),
+      hash: "hash_eu_v2",
+      fileId: "file_eu_v2"
+    }
+  },
+  rules: {
+    EU_RULE_TAX: {
+      id: "rule_eu_tax",
+      jurisdiction: "EU",
+      topicKey: "tax_reporting"
+    }
+  }
+};
+// src/ui/hooks/usePolicySafeKnowledgeAssistant.ts
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useTemplateRuntime } from "@contractspec/lib.example-shared-ui";
+"use client";
+function isCitationLike(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const v = value;
+  return typeof v.kbSnapshotId === "string" && typeof v.sourceId === "string";
+}
+function toCitations(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.filter(isCitationLike).map((c) => ({
+    kbSnapshotId: c.kbSnapshotId,
+    sourceId: c.sourceId,
+    excerpt: c.excerpt
+  }));
+}
+function usePolicySafeKnowledgeAssistant() {
+  const { handlers, projectId } = useTemplateRuntime();
+  const api = handlers.policySafeKnowledgeAssistant;
+  const [state, setState] = useState({
+    context: null,
+    loading: true,
+    error: null,
+    lastAnswer: null,
+    lastRuleId: null,
+    lastRuleVersionId: null,
+    lastSnapshotId: null,
+    lastReviewTaskId: null
+  });
+  const refreshContext = useCallback(async () => {
+    try {
+      setState((s) => ({ ...s, loading: true, error: null }));
+      const ctx = await api.getUserContext({ projectId });
+      setState((s) => ({
+        ...s,
+        context: {
+          locale: ctx.locale,
+          jurisdiction: ctx.jurisdiction,
+          allowedScope: ctx.allowedScope,
+          kbSnapshotId: ctx.kbSnapshotId
+        },
+        loading: false
+      }));
+    } catch (e) {
+      setState((s) => ({
+        ...s,
+        loading: false,
+        error: e instanceof Error ? e : new Error("Unknown error")
+      }));
+    }
+  }, [api, projectId]);
+  useEffect(() => {
+    refreshContext();
+  }, [refreshContext]);
+  const setContext = useCallback(async (input) => {
+    const ctx = await api.setUserContext({ projectId, ...input });
+    setState((s) => ({
+      ...s,
+      context: {
+        locale: ctx.locale,
+        jurisdiction: ctx.jurisdiction,
+        allowedScope: ctx.allowedScope,
+        kbSnapshotId: ctx.kbSnapshotId
+      }
+    }));
+  }, [api, projectId]);
+  const askAssistant = useCallback(async (question) => {
+    const answerUnknown = await api.answer({ projectId, question });
+    const answer = answerUnknown;
+    setState((s) => ({
+      ...s,
+      lastAnswer: {
+        refused: answer.refused,
+        refusalReason: answer.refusalReason,
+        sections: answer.sections,
+        citations: toCitations(answerUnknown.citations)
+      }
+    }));
+  }, [api, projectId]);
+  const createDemoRule = useCallback(async () => {
+    const rule = await api.createRule({
+      projectId,
+      jurisdiction: state.context?.jurisdiction ?? "EU",
+      topicKey: "tax_reporting"
+    });
+    setState((s) => ({ ...s, lastRuleId: rule.id }));
+    return rule.id;
+  }, [api, projectId, state.context?.jurisdiction]);
+  const upsertRuleVersion = useCallback(async (input) => {
+    const rv = await api.upsertRuleVersion({
+      projectId,
+      ruleId: input.ruleId,
+      content: input.content,
+      sourceRefs: [{ sourceDocumentId: "src_demo", excerpt: "demo excerpt" }]
+    });
+    setState((s) => ({ ...s, lastRuleVersionId: rv.id }));
+    return rv.id;
+  }, [api, projectId]);
+  const approveRuleVersion = useCallback(async (ruleVersionId) => {
+    await api.approveRuleVersion({ ruleVersionId, approver: "demo_expert" });
+  }, [api]);
+  const publishSnapshot = useCallback(async () => {
+    const snap = await api.publishSnapshot({
+      projectId,
+      jurisdiction: state.context?.jurisdiction ?? "EU",
+      asOfDate: new Date("2026-02-01T00:00:00.000Z")
+    });
+    setState((s) => ({ ...s, lastSnapshotId: snap.id }));
+    await refreshContext();
+    return snap.id;
+  }, [api, projectId, refreshContext, state.context?.jurisdiction]);
+  const simulateHighRiskChangeAndApprove = useCallback(async (ruleVersionId) => {
+    const cand = await api.createChangeCandidate({
+      projectId,
+      jurisdiction: state.context?.jurisdiction ?? "EU",
+      diffSummary: "Simulated change (demo)",
+      riskLevel: "high",
+      proposedRuleVersionIds: [ruleVersionId]
+    });
+    const review = await api.createReviewTask({ changeCandidateId: cand.id });
+    setState((s) => ({ ...s, lastReviewTaskId: review.id }));
+    await api.submitDecision({
+      reviewTaskId: review.id,
+      decision: "approve",
+      decidedByRole: "expert",
+      decidedBy: "demo_expert"
+    });
+    await api.publishIfReady({
+      jurisdiction: state.context?.jurisdiction ?? "EU"
+    });
+    return review.id;
+  }, [api, projectId, state.context?.jurisdiction]);
+  const derived = useMemo(() => ({ projectId }), [projectId]);
+  return {
+    state,
+    derived,
+    actions: {
+      refreshContext,
+      setContext,
+      askAssistant,
+      createDemoRule,
+      upsertRuleVersion,
+      approveRuleVersion,
+      publishSnapshot,
+      simulateHighRiskChangeAndApprove
+    }
+  };
+}
+
+// src/ui/PolicySafeKnowledgeAssistantDashboard.tsx
+import { useCallback as useCallback2, useMemo as useMemo2, useState as useState2 } from "react";
+import {
+  Button,
+  ErrorState,
+  LoaderBlock,
+  StatCard,
+  StatCardGroup
+} from "@contractspec/lib.design-system";
+import { Card } from "@contractspec/lib.ui-kit-web/ui/card";
+import { Input } from "@contractspec/lib.ui-kit-web/ui/input";
+import { Textarea } from "@contractspec/lib.ui-kit-web/ui/textarea";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue
+} from "@contractspec/lib.ui-kit-web/ui/select";
+import { jsxDEV } from "react/jsx-dev-runtime";
+"use client";
+function PolicySafeKnowledgeAssistantDashboard() {
+  const { state, actions } = usePolicySafeKnowledgeAssistant();
+  const [question, setQuestion] = useState2("reporting obligations");
+  const [content, setContent] = useState2("EU: Reporting obligations v2 (updated)");
+  const [locale, setLocale] = useState2("en-GB");
+  const [jurisdiction, setJurisdiction] = useState2("EU");
+  const [allowedScope, setAllowedScope] = useState2("education_only");
+  const snapshotId = state.context?.kbSnapshotId ?? state.lastSnapshotId ?? null;
+  const stats = useMemo2(() => {
+    return [
+      { label: "Locale", value: state.context?.locale ?? "\u2014" },
+      { label: "Jurisdiction", value: state.context?.jurisdiction ?? "\u2014" },
+      { label: "Scope", value: state.context?.allowedScope ?? "\u2014" },
+      { label: "KB Snapshot", value: snapshotId ?? "\u2014" }
+    ];
+  }, [
+    snapshotId,
+    state.context?.allowedScope,
+    state.context?.jurisdiction,
+    state.context?.locale
+  ]);
+  const handleSetContext = useCallback2(async () => {
+    await actions.setContext({ locale, jurisdiction, allowedScope });
+  }, [actions, allowedScope, jurisdiction, locale]);
+  const handleAsk = useCallback2(async () => {
+    await actions.askAssistant(question);
+  }, [actions, question]);
+  const handleAdminPublishFlow = useCallback2(async () => {
+    const ruleId = state.lastRuleId ?? await actions.createDemoRule();
+    const rvId = await actions.upsertRuleVersion({ ruleId, content });
+    await actions.approveRuleVersion(rvId);
+    await actions.simulateHighRiskChangeAndApprove(rvId);
+    await actions.publishSnapshot();
+  }, [actions, content, state.lastRuleId]);
+  if (state.loading && !state.context) {
+    return /* @__PURE__ */ jsxDEV(LoaderBlock, {
+      label: "Loading demo..."
+    }, undefined, false, undefined, this);
+  }
+  if (state.error) {
+    return /* @__PURE__ */ jsxDEV(ErrorState, {
+      title: "Failed to load demo",
+      description: state.error.message,
+      onRetry: actions.refreshContext,
+      retryLabel: "Retry"
+    }, undefined, false, undefined, this);
+  }
+  return /* @__PURE__ */ jsxDEV("div", {
+    className: "space-y-6",
+    children: [
+      /* @__PURE__ */ jsxDEV(StatCardGroup, {
+        children: stats.map((s) => /* @__PURE__ */ jsxDEV(StatCard, {
+          label: s.label,
+          value: String(s.value)
+        }, s.label, false, undefined, this))
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV(Card, {
+        className: "p-4",
+        children: [
+          /* @__PURE__ */ jsxDEV("h3", {
+            className: "text-lg font-semibold",
+            children: "1) Onboarding (explicit locale + jurisdiction)"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("div", {
+            className: "mt-3 grid gap-3 md:grid-cols-3",
+            children: [
+              /* @__PURE__ */ jsxDEV("div", {
+                children: [
+                  /* @__PURE__ */ jsxDEV("div", {
+                    className: "text-muted-foreground mb-1 text-xs font-semibold tracking-wide uppercase",
+                    children: "Locale"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV(Input, {
+                    value: locale,
+                    onChange: (e) => setLocale(e.target.value)
+                  }, undefined, false, undefined, this)
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV("div", {
+                children: [
+                  /* @__PURE__ */ jsxDEV("div", {
+                    className: "text-muted-foreground mb-1 text-xs font-semibold tracking-wide uppercase",
+                    children: "Jurisdiction"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV(Input, {
+                    value: jurisdiction,
+                    onChange: (e) => setJurisdiction(e.target.value)
+                  }, undefined, false, undefined, this)
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV("div", {
+                children: [
+                  /* @__PURE__ */ jsxDEV("div", {
+                    className: "text-muted-foreground mb-1 text-xs font-semibold tracking-wide uppercase",
+                    children: "Allowed scope"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV(Select, {
+                    value: allowedScope,
+                    onValueChange: (v) => setAllowedScope(v),
+                    children: [
+                      /* @__PURE__ */ jsxDEV(SelectTrigger, {
+                        children: /* @__PURE__ */ jsxDEV(SelectValue, {
+                          placeholder: "Select scope"
+                        }, undefined, false, undefined, this)
+                      }, undefined, false, undefined, this),
+                      /* @__PURE__ */ jsxDEV(SelectContent, {
+                        children: [
+                          /* @__PURE__ */ jsxDEV(SelectItem, {
+                            value: "education_only",
+                            children: "education_only"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV(SelectItem, {
+                            value: "generic_info",
+                            children: "generic_info"
+                          }, undefined, false, undefined, this),
+                          /* @__PURE__ */ jsxDEV(SelectItem, {
+                            value: "escalation_required",
+                            children: "escalation_required"
+                          }, undefined, false, undefined, this)
+                        ]
+                      }, undefined, true, undefined, this)
+                    ]
+                  }, undefined, true, undefined, this)
+                ]
+              }, undefined, true, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV("div", {
+            className: "mt-4 flex gap-2",
+            children: [
+              /* @__PURE__ */ jsxDEV(Button, {
+                onPress: handleSetContext,
+                children: "Save context"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV(Button, {
+                variant: "outline",
+                onPress: actions.refreshContext,
+                children: "Refresh"
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV(Card, {
+        className: "p-4",
+        children: [
+          /* @__PURE__ */ jsxDEV("h3", {
+            className: "text-lg font-semibold",
+            children: "2) Ask the assistant (must cite KB snapshot)"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("div", {
+            className: "mt-3 flex flex-col gap-3",
+            children: [
+              /* @__PURE__ */ jsxDEV(Input, {
+                value: question,
+                onChange: (e) => setQuestion(e.target.value)
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("div", {
+                className: "flex gap-2",
+                children: /* @__PURE__ */ jsxDEV(Button, {
+                  onPress: handleAsk,
+                  children: "Ask"
+                }, undefined, false, undefined, this)
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this),
+          state.lastAnswer ? /* @__PURE__ */ jsxDEV("div", {
+            className: "mt-4 space-y-3",
+            children: [
+              state.lastAnswer.refused ? /* @__PURE__ */ jsxDEV("div", {
+                className: "text-sm text-red-600",
+                children: [
+                  "Refused: ",
+                  state.lastAnswer.refusalReason ?? "UNKNOWN"
+                ]
+              }, undefined, true, undefined, this) : null,
+              state.lastAnswer.sections.map((s, idx) => /* @__PURE__ */ jsxDEV("div", {
+                children: [
+                  /* @__PURE__ */ jsxDEV("div", {
+                    className: "text-sm font-semibold",
+                    children: s.heading
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV("div", {
+                    className: "text-muted-foreground text-sm",
+                    children: s.body
+                  }, undefined, false, undefined, this)
+                ]
+              }, `${s.heading}-${idx}`, true, undefined, this)),
+              /* @__PURE__ */ jsxDEV("div", {
+                className: "text-sm font-semibold",
+                children: "Citations"
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("ul", {
+                className: "text-muted-foreground list-disc pl-5 text-sm",
+                children: state.lastAnswer.citations.map((c) => /* @__PURE__ */ jsxDEV("li", {
+                  children: [
+                    c.kbSnapshotId,
+                    " \u2014 ",
+                    c.sourceId
+                  ]
+                }, `${c.kbSnapshotId}-${c.sourceId}`, true, undefined, this))
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this) : null
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV(Card, {
+        className: "p-4",
+        children: [
+          /* @__PURE__ */ jsxDEV("h3", {
+            className: "text-lg font-semibold",
+            children: "3) Admin: publish a new snapshot (HITL)"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("div", {
+            className: "mt-3 space-y-3",
+            children: [
+              /* @__PURE__ */ jsxDEV(Textarea, {
+                value: content,
+                onChange: (e) => setContent(e.target.value)
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV(Button, {
+                onPress: handleAdminPublishFlow,
+                children: "Simulate change \u2192 review \u2192 approve \u2192 publish snapshot"
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV(Card, {
+        className: "p-4",
+        children: [
+          /* @__PURE__ */ jsxDEV("h3", {
+            className: "text-lg font-semibold",
+            children: "4) Learning hub (patterns)"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("p", {
+            className: "text-muted-foreground mt-2 text-sm",
+            children: "This template includes drills, ambient coach, and quests as reusable Learning Journey tracks. The interactive learning UI is demonstrated in dedicated Learning Journey examples."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+export {
+  example_default as example,
+  createPolicySafeKnowledgeAssistantHandlers,
+  buildPolicySafeAnswer,
+  PolicySafeKnowledgeAssistantFeature,
+  PolicySafeKnowledgeAssistantDashboard,
+  DEMO_FIXTURES
+};