@contractspec/example.policy-safe-knowledge-assistant 3.7.17 → 3.7.18

package/dist/node/index.js

@@ -1,15 +1,4 @@
-// src/docs/policy-safe-knowledge-assistant.docblock.ts
-import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
-var docBlocks = [
-  {
-    id: "docs.examples.policy-safe-knowledge-assistant.goal",
-    title: "Policy-safe Knowledge Assistant — 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
+import{registerDocBlocks as b}from"@contractspec/lib.contracts-spec/docs";var x=[{id:"docs.examples.policy-safe-knowledge-assistant.goal",title:"Policy-safe Knowledge Assistant — 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.
@@ -17,908 +6,13 @@ var docBlocks = [
 
 ## 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 — Usage",
-    summary: "5–10 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)
+- 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 — Usage",summary:"5–10 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-spec";
-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-spec";
-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" }
-    ]
-  },
-  policies: [{ key: "policy-safe.policy.gate", version: "1.0.0" }],
-  knowledge: [{ key: "policy-safe.knowledge.rules", version: "1.0.0" }],
-  jobs: [{ key: "policy-safe.job.pipeline-watch", version: "1.0.0" }],
-  docs: [
-    "docs.examples.policy-safe-knowledge-assistant.goal",
-    "docs.examples.policy-safe-knowledge-assistant.usage"
-  ]
-});
-
-// 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 { useTemplateRuntime } from "@contractspec/lib.example-shared-ui";
-import { useCallback, useEffect, useMemo, useState } from "react";
-"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 {
-  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 {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue
-} from "@contractspec/lib.ui-kit-web/ui/select";
-import { Textarea } from "@contractspec/lib.ui-kit-web/ui/textarea";
-import { useCallback as useCallback2, useMemo as useMemo2, useState as useState2 } from "react";
-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 ?? "—" },
-      { label: "Jurisdiction", value: state.context?.jurisdiction ?? "—" },
-      { label: "Scope", value: state.context?.allowedScope ?? "—" },
-      { label: "KB Snapshot", value: snapshotId ?? "—" }
-    ];
-  }, [
-    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: "font-semibold text-lg",
-            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: "mb-1 font-semibold text-muted-foreground text-xs uppercase tracking-wide",
-                    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: "mb-1 font-semibold text-muted-foreground text-xs uppercase tracking-wide",
-                    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: "mb-1 font-semibold text-muted-foreground text-xs uppercase tracking-wide",
-                    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: "font-semibold text-lg",
-            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-red-600 text-sm",
-                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: "font-semibold text-sm",
-                    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: "font-semibold text-sm",
-                children: "Citations"
-              }, undefined, false, undefined, this),
-              /* @__PURE__ */ jsxDEV("ul", {
-                className: "list-disc pl-5 text-muted-foreground text-sm",
-                children: state.lastAnswer.citations.map((c) => /* @__PURE__ */ jsxDEV("li", {
-                  children: [
-                    c.kbSnapshotId,
-                    " — ",
-                    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: "font-semibold text-lg",
-            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 → review → approve → 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: "font-semibold text-lg",
-            children: "4) Learning hub (patterns)"
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsxDEV("p", {
-            className: "mt-2 text-muted-foreground 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
-};
+5) Learning hub: drills session, ambient tip, quest start + step completion.`}];b(x);import{defineExample as l}from"@contractspec/lib.contracts-spec";var o=l({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:!0,sandbox:{enabled:!0,modes:["playground","specs","builder","markdown","evolution"]},studio:{enabled:!0,installable:!0},mcp:{enabled:!0}}}),c=o;import{enforceAllowedScope as r,enforceCitations as d,validateEnvelope as a}from"@contractspec/example.locale-jurisdiction-gate/policy/guard";async function k(E){let U=a(E.envelope);if(!U.ok)return{locale:E.envelope.locale??"en-GB",jurisdiction:E.envelope.regulatoryContext?.jurisdiction??"UNKNOWN",allowedScope:E.envelope.allowedScope??"education_only",sections:[{heading:"Request blocked",body:U.error.message}],citations:[],disclaimers:["This system refuses to answer without a valid envelope."],riskFlags:[U.error.code],refused:!0,refusalReason:U.error.code};let Z=await E.kbSearch({snapshotId:U.value.kbSnapshotId,jurisdiction:U.value.regulatoryContext?.jurisdiction??"UNKNOWN",query:E.question}),N=Z.items.map((H)=>({kbSnapshotId:U.value.kbSnapshotId,sourceType:"ruleVersion",sourceId:H.ruleVersionId,title:"Curated rule version",excerpt:H.excerpt})),z={locale:U.value.locale,jurisdiction:U.value.regulatoryContext?.jurisdiction??"UNKNOWN",allowedScope:U.value.allowedScope,sections:[{heading:"Answer (KB-derived)",body:Z.items.length>0?`This answer is derived from ${Z.items.length} curated rule version(s) in the referenced snapshot.`:"No curated knowledge found in the referenced snapshot."}],citations:N,disclaimers:["Educational demo only."],riskFlags:[]},W=r(U.value.allowedScope,z);if(!W.ok)return{...z,sections:[{heading:"Escalation required",body:W.error.message}],refused:!0,refusalReason:W.error.code,riskFlags:[...z.riskFlags??[],W.error.code]};let Y=d(z);if(!Y.ok)return{...z,sections:[{heading:"Request blocked",body:Y.error.message}],citations:[],refused:!0,refusalReason:Y.error.code,riskFlags:[...z.riskFlags??[],Y.error.code]};return z}import{web as u}from"@contractspec/lib.runtime-sandbox";var{generateId:K}=u;function I(E){if(!E)return[];try{let U=JSON.parse(E);return Array.isArray(U)?U.filter((Z)=>typeof Z==="string"):[]}catch{return[]}}function V(){return new Date().toISOString()}function J0(E){async function U(_){let O=(await E.query('SELECT * FROM psa_user_context WHERE "projectId" = $1 LIMIT 1',[_.projectId])).rows[0];if(!O)return{projectId:_.projectId,locale:"en-GB",jurisdiction:"EU",allowedScope:"education_only",kbSnapshotId:null};return{projectId:O.projectId,locale:O.locale,jurisdiction:O.jurisdiction,allowedScope:O.allowedScope,kbSnapshotId:O.kbSnapshotId}}async function Z(_){if((await E.query('SELECT "projectId" FROM psa_user_context WHERE "projectId" = $1 LIMIT 1',[_.projectId])).rows.length)await E.execute('UPDATE psa_user_context SET locale = $1, jurisdiction = $2, "allowedScope" = $3 WHERE "projectId" = $4',[_.locale,_.jurisdiction,_.allowedScope,_.projectId]);else await E.execute('INSERT INTO psa_user_context ("projectId", locale, jurisdiction, "allowedScope", "kbSnapshotId") VALUES ($1, $2, $3, $4, $5)',[_.projectId,_.locale,_.jurisdiction,_.allowedScope,null]);return await U({projectId:_.projectId})}async function N(_){let D=K("psa_rule");return await E.execute('INSERT INTO psa_rule (id, "projectId", jurisdiction, "topicKey") VALUES ($1, $2, $3, $4)',[D,_.projectId,_.jurisdiction,_.topicKey]),{id:D,..._}}async function z(_){if(!_.sourceRefs.length)throw Error("SOURCE_REFS_REQUIRED");let O=(await E.query("SELECT * FROM psa_rule WHERE id = $1 LIMIT 1",[_.ruleId])).rows[0];if(!O)throw Error("RULE_NOT_FOUND");let T=await E.query('SELECT MAX(version) as maxVersion FROM psa_rule_version WHERE "ruleId" = $1',[_.ruleId]),M=Number(T.rows[0]?.maxVersion??0)+1,$=K("psa_rv"),R=V();return await E.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)`,[$,_.ruleId,O.jurisdiction,O.topicKey,M,_.content,"draft",JSON.stringify(_.sourceRefs),null,null,R]),{id:$,ruleId:_.ruleId,jurisdiction:O.jurisdiction,topicKey:O.topicKey,version:M,content:_.content,status:"draft",sourceRefs:_.sourceRefs,createdAt:new Date(R)}}async function W(_){let D=V();return await E.execute('UPDATE psa_rule_version SET status = $1, "approvedBy" = $2, "approvedAt" = $3 WHERE id = $4',["approved",_.approver,D,_.ruleVersionId]),{ruleVersionId:_.ruleVersionId,status:"approved"}}async function Y(_){let O=(await E.query("SELECT id FROM psa_rule_version WHERE jurisdiction = $1 AND status = 'approved' ORDER BY id ASC",[_.jurisdiction])).rows.map((M)=>M.id).filter(Boolean);if(!O.length)throw Error("NO_APPROVED_RULES");let T=K("psa_snap"),X=V();return await E.execute(`INSERT INTO psa_snapshot (id, jurisdiction, "asOfDate", "includedRuleVersionIdsJson", "publishedAt")
+       VALUES ($1, $2, $3, $4, $5)`,[T,_.jurisdiction,_.asOfDate.toISOString(),JSON.stringify(O),X]),await E.execute('UPDATE psa_user_context SET "kbSnapshotId" = $1 WHERE "projectId" = $2',[T,_.projectId]),{id:T,jurisdiction:_.jurisdiction,includedRuleVersionIds:O}}async function H(_){let O=(await E.query("SELECT * FROM psa_snapshot WHERE id = $1 LIMIT 1",[_.snapshotId])).rows[0];if(!O)throw Error("SNAPSHOT_NOT_FOUND");if(O.jurisdiction!==_.jurisdiction)throw Error("JURISDICTION_MISMATCH");let T=I(O.includedRuleVersionIdsJson),X=_.query.toLowerCase().split(/\s+/).map(($)=>$.trim()).filter(Boolean),M=[];for(let $ of T){let P=(await E.query("SELECT * FROM psa_rule_version WHERE id = $1 LIMIT 1",[$])).rows[0];if(!P)continue;let f=P.content.toLowerCase();if(!(X.length?X.every((j)=>f.includes(j)):!0))continue;M.push({ruleVersionId:P.id,excerpt:P.content.slice(0,140)})}return{items:M}}async function Q(_){let D=await U({projectId:_.projectId});if(!D.kbSnapshotId)return await k({envelope:{traceId:K("trace"),locale:D.locale,kbSnapshotId:"",allowedScope:D.allowedScope,regulatoryContext:{jurisdiction:D.jurisdiction}},question:_.question,kbSearch:async()=>({items:[]})});return await k({envelope:{traceId:K("trace"),locale:D.locale,kbSnapshotId:D.kbSnapshotId,allowedScope:D.allowedScope,regulatoryContext:{jurisdiction:D.jurisdiction}},question:_.question,kbSearch:async(O)=>await H(O)})}async function q(_){let D=K("psa_change");return await E.execute(`INSERT INTO psa_change_candidate (id, "projectId", jurisdiction, "detectedAt", "diffSummary", "riskLevel", "proposedRuleVersionIdsJson")
+       VALUES ($1, $2, $3, $4, $5, $6, $7)`,[D,_.projectId,_.jurisdiction,V(),_.diffSummary,_.riskLevel,JSON.stringify(_.proposedRuleVersionIds)]),{id:D}}async function J(_){let O=(await E.query("SELECT * FROM psa_change_candidate WHERE id = $1 LIMIT 1",[_.changeCandidateId])).rows[0];if(!O)throw Error("CHANGE_CANDIDATE_NOT_FOUND");let T=O.riskLevel==="high"?"expert":"curator",X=K("psa_review");return await E.execute(`INSERT INTO psa_review_task (id, "changeCandidateId", status, "assignedRole", decision, "decidedAt", "decidedBy")
+       VALUES ($1, $2, $3, $4, $5, $6, $7)`,[X,_.changeCandidateId,"open",T,null,null,null]),{id:X,assignedRole:T}}async function y(_){let O=(await E.query("SELECT * FROM psa_review_task WHERE id = $1 LIMIT 1",[_.reviewTaskId])).rows[0];if(!O)throw Error("REVIEW_TASK_NOT_FOUND");let X=(await E.query("SELECT * FROM psa_change_candidate WHERE id = $1 LIMIT 1",[O.changeCandidateId])).rows[0];if(!X)throw Error("CHANGE_CANDIDATE_NOT_FOUND");if(X.riskLevel==="high"&&_.decision==="approve"&&_.decidedByRole!=="expert")throw Error("FORBIDDEN_ROLE");let M=V();return await E.execute('UPDATE psa_review_task SET status = $1, decision = $2, "decidedAt" = $3, "decidedBy" = $4 WHERE id = $5',["decided",_.decision,M,_.decidedBy,_.reviewTaskId]),{id:_.reviewTaskId,status:"decided"}}async function B(_){let D=await E.query("SELECT COUNT(*) as count FROM psa_review_task WHERE status != 'decided'",[]);if(Number(D.rows[0]?.count??0)>0)throw Error("NOT_READY");let T=await E.query("SELECT * FROM psa_review_task",[]);for(let X of T.rows){if(X.decision!=="approve")continue;let $=(await E.query("SELECT * FROM psa_change_candidate WHERE id = $1 LIMIT 1",[X.changeCandidateId])).rows[0];if(!$)continue;if($.jurisdiction!==_.jurisdiction)continue;let R=I($.proposedRuleVersionIdsJson);for(let P of R){let f=await E.query("SELECT status FROM psa_rule_version WHERE id = $1 LIMIT 1",[P]);if(String(f.rows[0]?.status??"")!=="approved")throw Error("NOT_READY")}}return{published:!0}}return{getUserContext:U,setUserContext:Z,createRule:N,upsertRuleVersion:z,approveRuleVersion:W,publishSnapshot:Y,searchKb:H,answer:Q,createChangeCandidate:q,createReviewTask:J,submitDecision:y,publishIfReady:B}}import{defineFeature as p}from"@contractspec/lib.contracts-spec";var P0=p({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"}]},policies:[{key:"policy-safe.policy.gate",version:"1.0.0"}],knowledge:[{key:"policy-safe.knowledge.rules",version:"1.0.0"}],jobs:[{key:"policy-safe.job.pipeline-watch",version:"1.0.0"}],docs:["docs.examples.policy-safe-knowledge-assistant.goal","docs.examples.policy-safe-knowledge-assistant.usage"]});var y0={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"}}};import{useTemplateRuntime as i}from"@contractspec/lib.example-shared-ui";import{useCallback as L,useEffect as s,useMemo as n,useState as e}from"react";function t(E){if(!E||typeof E!=="object")return!1;let U=E;return typeof U.kbSnapshotId==="string"&&typeof U.sourceId==="string"}function _0(E){if(!Array.isArray(E))return[];return E.filter(t).map((U)=>({kbSnapshotId:U.kbSnapshotId,sourceId:U.sourceId,excerpt:U.excerpt}))}function v(){let{handlers:E,projectId:U}=i(),Z=E.policySafeKnowledgeAssistant,[N,z]=e({context:null,loading:!0,error:null,lastAnswer:null,lastRuleId:null,lastRuleVersionId:null,lastSnapshotId:null,lastReviewTaskId:null}),W=L(async()=>{try{z((O)=>({...O,loading:!0,error:null}));let D=await Z.getUserContext({projectId:U});z((O)=>({...O,context:{locale:D.locale,jurisdiction:D.jurisdiction,allowedScope:D.allowedScope,kbSnapshotId:D.kbSnapshotId},loading:!1}))}catch(D){z((O)=>({...O,loading:!1,error:D instanceof Error?D:Error("Unknown error")}))}},[Z,U]);s(()=>{W()},[W]);let Y=L(async(D)=>{let O=await Z.setUserContext({projectId:U,...D});z((T)=>({...T,context:{locale:O.locale,jurisdiction:O.jurisdiction,allowedScope:O.allowedScope,kbSnapshotId:O.kbSnapshotId}}))},[Z,U]),H=L(async(D)=>{let O=await Z.answer({projectId:U,question:D}),T=O;z((X)=>({...X,lastAnswer:{refused:T.refused,refusalReason:T.refusalReason,sections:T.sections,citations:_0(O.citations)}}))},[Z,U]),Q=L(async()=>{let D=await Z.createRule({projectId:U,jurisdiction:N.context?.jurisdiction??"EU",topicKey:"tax_reporting"});return z((O)=>({...O,lastRuleId:D.id})),D.id},[Z,U,N.context?.jurisdiction]),q=L(async(D)=>{let O=await Z.upsertRuleVersion({projectId:U,ruleId:D.ruleId,content:D.content,sourceRefs:[{sourceDocumentId:"src_demo",excerpt:"demo excerpt"}]});return z((T)=>({...T,lastRuleVersionId:O.id})),O.id},[Z,U]),J=L(async(D)=>{await Z.approveRuleVersion({ruleVersionId:D,approver:"demo_expert"})},[Z]),y=L(async()=>{let D=await Z.publishSnapshot({projectId:U,jurisdiction:N.context?.jurisdiction??"EU",asOfDate:new Date("2026-02-01T00:00:00.000Z")});return z((O)=>({...O,lastSnapshotId:D.id})),await W(),D.id},[Z,U,W,N.context?.jurisdiction]),B=L(async(D)=>{let O=await Z.createChangeCandidate({projectId:U,jurisdiction:N.context?.jurisdiction??"EU",diffSummary:"Simulated change (demo)",riskLevel:"high",proposedRuleVersionIds:[D]}),T=await Z.createReviewTask({changeCandidateId:O.id});return z((X)=>({...X,lastReviewTaskId:T.id})),await Z.submitDecision({reviewTaskId:T.id,decision:"approve",decidedByRole:"expert",decidedBy:"demo_expert"}),await Z.publishIfReady({jurisdiction:N.context?.jurisdiction??"EU"}),T.id},[Z,U,N.context?.jurisdiction]),_=n(()=>({projectId:U}),[U]);return{state:N,derived:_,actions:{refreshContext:W,setContext:Y,askAssistant:H,createDemoRule:Q,upsertRuleVersion:q,approveRuleVersion:J,publishSnapshot:y,simulateHighRiskChangeAndApprove:B}}}import{Button as m,ErrorState as E0,LoaderBlock as U0,StatCard as O0,StatCardGroup as D0}from"@contractspec/lib.design-system";import{Card as A}from"@contractspec/lib.ui-kit-web/ui/card";import{Input as g}from"@contractspec/lib.ui-kit-web/ui/input";import{Select as X0,SelectContent as Z0,SelectItem as S,SelectTrigger as F0,SelectValue as T0}from"@contractspec/lib.ui-kit-web/ui/select";import{Textarea as z0}from"@contractspec/lib.ui-kit-web/ui/textarea";import{useCallback as C,useMemo as G0,useState as h}from"react";import{jsx as F,jsxs as G}from"react/jsx-runtime";function j0(){let{state:E,actions:U}=v(),[Z,N]=h("reporting obligations"),[z,W]=h("EU: Reporting obligations v2 (updated)"),[Y,H]=h("en-GB"),[Q,q]=h("EU"),[J,y]=h("education_only"),B=E.context?.kbSnapshotId??E.lastSnapshotId??null,_=G0(()=>{return[{label:"Locale",value:E.context?.locale??"—"},{label:"Jurisdiction",value:E.context?.jurisdiction??"—"},{label:"Scope",value:E.context?.allowedScope??"—"},{label:"KB Snapshot",value:B??"—"}]},[B,E.context?.allowedScope,E.context?.jurisdiction,E.context?.locale]),D=C(async()=>{await U.setContext({locale:Y,jurisdiction:Q,allowedScope:J})},[U,J,Q,Y]),O=C(async()=>{await U.askAssistant(Z)},[U,Z]),T=C(async()=>{let X=E.lastRuleId??await U.createDemoRule(),M=await U.upsertRuleVersion({ruleId:X,content:z});await U.approveRuleVersion(M),await U.simulateHighRiskChangeAndApprove(M),await U.publishSnapshot()},[U,z,E.lastRuleId]);if(E.loading&&!E.context)return F(U0,{label:"Loading demo..."});if(E.error)return F(E0,{title:"Failed to load demo",description:E.error.message,onRetry:U.refreshContext,retryLabel:"Retry"});return G("div",{className:"space-y-6",children:[F(D0,{children:_.map((X)=>F(O0,{label:X.label,value:String(X.value)},X.label))}),G(A,{className:"p-4",children:[F("h3",{className:"font-semibold text-lg",children:"1) Onboarding (explicit locale + jurisdiction)"}),G("div",{className:"mt-3 grid gap-3 md:grid-cols-3",children:[G("div",{children:[F("div",{className:"mb-1 font-semibold text-muted-foreground text-xs uppercase tracking-wide",children:"Locale"}),F(g,{value:Y,onChange:(X)=>H(X.target.value)})]}),G("div",{children:[F("div",{className:"mb-1 font-semibold text-muted-foreground text-xs uppercase tracking-wide",children:"Jurisdiction"}),F(g,{value:Q,onChange:(X)=>q(X.target.value)})]}),G("div",{children:[F("div",{className:"mb-1 font-semibold text-muted-foreground text-xs uppercase tracking-wide",children:"Allowed scope"}),G(X0,{value:J,onValueChange:(X)=>y(X),children:[F(F0,{children:F(T0,{placeholder:"Select scope"})}),G(Z0,{children:[F(S,{value:"education_only",children:"education_only"}),F(S,{value:"generic_info",children:"generic_info"}),F(S,{value:"escalation_required",children:"escalation_required"})]})]})]})]}),G("div",{className:"mt-4 flex gap-2",children:[F(m,{onPress:D,children:"Save context"}),F(m,{variant:"outline",onPress:U.refreshContext,children:"Refresh"})]})]}),G(A,{className:"p-4",children:[F("h3",{className:"font-semibold text-lg",children:"2) Ask the assistant (must cite KB snapshot)"}),G("div",{className:"mt-3 flex flex-col gap-3",children:[F(g,{value:Z,onChange:(X)=>N(X.target.value)}),F("div",{className:"flex gap-2",children:F(m,{onPress:O,children:"Ask"})})]}),E.lastAnswer?G("div",{className:"mt-4 space-y-3",children:[E.lastAnswer.refused?G("div",{className:"text-red-600 text-sm",children:["Refused: ",E.lastAnswer.refusalReason??"UNKNOWN"]}):null,E.lastAnswer.sections.map((X,M)=>G("div",{children:[F("div",{className:"font-semibold text-sm",children:X.heading}),F("div",{className:"text-muted-foreground text-sm",children:X.body})]},`${X.heading}-${M}`)),F("div",{className:"font-semibold text-sm",children:"Citations"}),F("ul",{className:"list-disc pl-5 text-muted-foreground text-sm",children:E.lastAnswer.citations.map((X)=>G("li",{children:[X.kbSnapshotId," — ",X.sourceId]},`${X.kbSnapshotId}-${X.sourceId}`))})]}):null]}),G(A,{className:"p-4",children:[F("h3",{className:"font-semibold text-lg",children:"3) Admin: publish a new snapshot (HITL)"}),G("div",{className:"mt-3 space-y-3",children:[F(z0,{value:z,onChange:(X)=>W(X.target.value)}),F(m,{onPress:T,children:"Simulate change → review → approve → publish snapshot"})]})]}),G(A,{className:"p-4",children:[F("h3",{className:"font-semibold text-lg",children:"4) Learning hub (patterns)"}),F("p",{className:"mt-2 text-muted-foreground 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."})]})]})}export{c as example,J0 as createPolicySafeKnowledgeAssistantHandlers,k as buildPolicySafeAnswer,P0 as PolicySafeKnowledgeAssistantFeature,j0 as PolicySafeKnowledgeAssistantDashboard,y0 as DEMO_FIXTURES};