@contractspec/example.policy-safe-knowledge-assistant 0.0.0-canary-20260113170453

package/dist/ui/hooks/usePolicySafeKnowledgeAssistant.js

@@ -0,0 +1,193 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useTemplateRuntime } from "@contractspec/lib.example-shared-ui";
+
+//#region src/ui/hooks/usePolicySafeKnowledgeAssistant.ts
+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 : /* @__PURE__ */ 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: /* @__PURE__ */ 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
+	]);
+	return {
+		state,
+		derived: useMemo(() => ({ projectId }), [projectId]),
+		actions: {
+			refreshContext,
+			setContext,
+			askAssistant,
+			createDemoRule,
+			upsertRuleVersion,
+			approveRuleVersion,
+			publishSnapshot,
+			simulateHighRiskChangeAndApprove
+		}
+	};
+}
+
+//#endregion
+export { usePolicySafeKnowledgeAssistant };
+//# sourceMappingURL=usePolicySafeKnowledgeAssistant.js.map

package/dist/ui/hooks/usePolicySafeKnowledgeAssistant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePolicySafeKnowledgeAssistant.js","names":[],"sources":["../../../src/ui/hooks/usePolicySafeKnowledgeAssistant.ts"],"sourcesContent":["'use client';\n\nimport { useCallback, useEffect, useMemo, useState } from 'react';\nimport { useTemplateRuntime } from '@contractspec/lib.example-shared-ui';\n\ntype AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';\ntype RiskLevel = 'low' | 'medium' | 'high';\n\nexport interface UsePolicySafeKnowledgeAssistantState {\n  context: {\n    locale: string;\n    jurisdiction: string;\n    allowedScope: AllowedScope;\n    kbSnapshotId: string | null;\n  } | null;\n  loading: boolean;\n  error: Error | null;\n  lastAnswer: {\n    refused?: boolean;\n    refusalReason?: string;\n    sections: { heading: string; body: string }[];\n    citations: {\n      kbSnapshotId: string;\n      sourceId: string;\n      excerpt?: string;\n    }[];\n  } | null;\n  lastRuleId: string | null;\n  lastRuleVersionId: string | null;\n  lastSnapshotId: string | null;\n  lastReviewTaskId: string | null;\n}\n\ninterface CitationLike {\n  kbSnapshotId: string;\n  sourceId: string;\n  excerpt?: string;\n}\ninterface AnswerLike {\n  refused?: boolean;\n  refusalReason?: string;\n  sections: { heading: string; body: string }[];\n  citations: CitationLike[];\n}\n\nfunction isCitationLike(value: unknown): value is CitationLike {\n  if (!value || typeof value !== 'object') return false;\n  const v = value as Record<string, unknown>;\n  return typeof v.kbSnapshotId === 'string' && typeof v.sourceId === 'string';\n}\n\nfunction toCitations(value: unknown): CitationLike[] {\n  if (!Array.isArray(value)) return [];\n  return value.filter(isCitationLike).map((c) => ({\n    kbSnapshotId: c.kbSnapshotId,\n    sourceId: c.sourceId,\n    excerpt: c.excerpt,\n  }));\n}\n\nimport type { PolicySafeKnowledgeAssistantHandlers } from '../../handlers/policy-safe-knowledge-assistant.handlers';\n\nexport function usePolicySafeKnowledgeAssistant() {\n  const { handlers, projectId } = useTemplateRuntime<{\n    policySafeKnowledgeAssistant: PolicySafeKnowledgeAssistantHandlers;\n  }>();\n  const api = handlers.policySafeKnowledgeAssistant;\n\n  const [state, setState] = useState<UsePolicySafeKnowledgeAssistantState>({\n    context: null,\n    loading: true,\n    error: null,\n    lastAnswer: null,\n    lastRuleId: null,\n    lastRuleVersionId: null,\n    lastSnapshotId: null,\n    lastReviewTaskId: null,\n  });\n\n  const refreshContext = useCallback(async () => {\n    try {\n      setState((s) => ({ ...s, loading: true, error: null }));\n      const ctx = await api.getUserContext({ projectId });\n      setState((s) => ({\n        ...s,\n        context: {\n          locale: ctx.locale,\n          jurisdiction: ctx.jurisdiction,\n          allowedScope: ctx.allowedScope,\n          kbSnapshotId: ctx.kbSnapshotId,\n        },\n        loading: false,\n      }));\n    } catch (e) {\n      setState((s) => ({\n        ...s,\n        loading: false,\n        error: e instanceof Error ? e : new Error('Unknown error'),\n      }));\n    }\n  }, [api, projectId]);\n\n  useEffect(() => {\n    refreshContext();\n  }, [refreshContext]);\n\n  const setContext = useCallback(\n    async (input: {\n      locale: string;\n      jurisdiction: string;\n      allowedScope: AllowedScope;\n    }) => {\n      const ctx = await api.setUserContext({ projectId, ...input });\n      setState((s) => ({\n        ...s,\n        context: {\n          locale: ctx.locale,\n          jurisdiction: ctx.jurisdiction,\n          allowedScope: ctx.allowedScope,\n          kbSnapshotId: ctx.kbSnapshotId,\n        },\n      }));\n    },\n    [api, projectId]\n  );\n\n  const askAssistant = useCallback(\n    async (question: string) => {\n      const answerUnknown: unknown = await api.answer({ projectId, question });\n      const answer = answerUnknown as AnswerLike;\n      setState((s) => ({\n        ...s,\n        lastAnswer: {\n          refused: answer.refused,\n          refusalReason: answer.refusalReason,\n          sections: answer.sections,\n          citations: toCitations(\n            (answerUnknown as { citations?: unknown }).citations\n          ),\n        },\n      }));\n    },\n    [api, projectId]\n  );\n\n  const createDemoRule = useCallback(async () => {\n    const rule = await api.createRule({\n      projectId,\n      jurisdiction: state.context?.jurisdiction ?? 'EU',\n      topicKey: 'tax_reporting',\n    });\n    setState((s) => ({ ...s, lastRuleId: rule.id }));\n    return rule.id as string;\n  }, [api, projectId, state.context?.jurisdiction]);\n\n  const upsertRuleVersion = useCallback(\n    async (input: { ruleId: string; content: string }) => {\n      const rv = await api.upsertRuleVersion({\n        projectId,\n        ruleId: input.ruleId,\n        content: input.content,\n        sourceRefs: [{ sourceDocumentId: 'src_demo', excerpt: 'demo excerpt' }],\n      });\n      setState((s) => ({ ...s, lastRuleVersionId: rv.id }));\n      return rv.id as string;\n    },\n    [api, projectId]\n  );\n\n  const approveRuleVersion = useCallback(\n    async (ruleVersionId: string) => {\n      await api.approveRuleVersion({ ruleVersionId, approver: 'demo_expert' });\n    },\n    [api]\n  );\n\n  const publishSnapshot = useCallback(async () => {\n    const snap = await api.publishSnapshot({\n      projectId,\n      jurisdiction: state.context?.jurisdiction ?? 'EU',\n      asOfDate: new Date('2026-02-01T00:00:00.000Z'),\n    });\n    setState((s) => ({ ...s, lastSnapshotId: snap.id }));\n    await refreshContext();\n    return snap.id as string;\n  }, [api, projectId, refreshContext, state.context?.jurisdiction]);\n\n  const simulateHighRiskChangeAndApprove = useCallback(\n    async (ruleVersionId: string) => {\n      const cand = await api.createChangeCandidate({\n        projectId,\n        jurisdiction: state.context?.jurisdiction ?? 'EU',\n        diffSummary: 'Simulated change (demo)',\n        riskLevel: 'high' satisfies RiskLevel,\n        proposedRuleVersionIds: [ruleVersionId],\n      });\n      const review = await api.createReviewTask({ changeCandidateId: cand.id });\n      setState((s) => ({ ...s, lastReviewTaskId: review.id }));\n      await api.submitDecision({\n        reviewTaskId: review.id,\n        decision: 'approve',\n        decidedByRole: 'expert',\n        decidedBy: 'demo_expert',\n      });\n      await api.publishIfReady({\n        jurisdiction: state.context?.jurisdiction ?? 'EU',\n      });\n      return review.id as string;\n    },\n    [api, projectId, state.context?.jurisdiction]\n  );\n\n  const derived = useMemo(() => ({ projectId }), [projectId]);\n\n  return {\n    state,\n    derived,\n    actions: {\n      refreshContext,\n      setContext,\n      askAssistant,\n      createDemoRule,\n      upsertRuleVersion,\n      approveRuleVersion,\n      publishSnapshot,\n      simulateHighRiskChangeAndApprove,\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/ui/index.d.ts

@@ -0,0 +1,2 @@
+import { PolicySafeKnowledgeAssistantDashboard } from "./PolicySafeKnowledgeAssistantDashboard.js";
+export { PolicySafeKnowledgeAssistantDashboard };

package/dist/ui/index.js

@@ -0,0 +1,3 @@
+import { PolicySafeKnowledgeAssistantDashboard } from "./PolicySafeKnowledgeAssistantDashboard.js";
+
+export { PolicySafeKnowledgeAssistantDashboard };

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@contractspec/example.policy-safe-knowledge-assistant",
+  "version": "0.0.0-canary-20260113170453",
+  "description": "All-in-one template example: policy-safe knowledge assistant with locale/jurisdiction gating, versioned KB snapshots, HITL update pipeline, and learning hub.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/policy-safe-knowledge-assistant.docblock": "./dist/docs/policy-safe-knowledge-assistant.docblock.js",
+    "./example": "./dist/example.js",
+    "./handlers": "./dist/handlers/index.js",
+    "./handlers/policy-safe-knowledge-assistant.handlers": "./dist/handlers/policy-safe-knowledge-assistant.handlers.js",
+    "./orchestrator/buildAnswer": "./dist/orchestrator/buildAnswer.js",
+    "./policy-safe-knowledge-assistant.feature": "./dist/policy-safe-knowledge-assistant.feature.js",
+    "./seed": "./dist/seed/index.js",
+    "./seed/fixtures": "./dist/seed/fixtures.js",
+    "./seeders": "./dist/seeders/index.js",
+    "./ui": "./dist/ui/index.js",
+    "./ui/hooks/usePolicySafeKnowledgeAssistant": "./dist/ui/hooks/usePolicySafeKnowledgeAssistant.js",
+    "./ui/PolicySafeKnowledgeAssistantDashboard": "./dist/ui/PolicySafeKnowledgeAssistantDashboard.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@contractspec/example.kb-update-pipeline": "0.0.0-canary-20260113170453",
+    "@contractspec/example.learning-patterns": "0.0.0-canary-20260113170453",
+    "@contractspec/example.locale-jurisdiction-gate": "0.0.0-canary-20260113170453",
+    "@contractspec/example.versioned-knowledge-base": "0.0.0-canary-20260113170453",
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113170453",
+    "@contractspec/lib.design-system": "0.0.0-canary-20260113170453",
+    "@contractspec/lib.example-shared-ui": "0.0.0-canary-20260113170453",
+    "@contractspec/lib.runtime-sandbox": "0.0.0-canary-20260113170453",
+    "@contractspec/lib.ui-kit-web": "0.0.0-canary-20260113170453",
+    "@contractspec/module.learning-journey": "0.0.0-canary-20260113170453",
+    "react": "19.2.3",
+    "react-dom": "19.2.3"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113170453",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113170453",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3",
+    "@types/react": "^19.2.8",
+    "@types/react-dom": "^19.2.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/policy-safe-knowledge-assistant.docblock": "./dist/docs/policy-safe-knowledge-assistant.docblock.js",
+      "./example": "./dist/example.js",
+      "./policy-safe-knowledge-assistant.feature": "./dist/policy-safe-knowledge-assistant.feature.js",
+      "./orchestrator/buildAnswer": "./dist/orchestrator/buildAnswer.js",
+      "./seed": "./dist/seed/index.js",
+      "./seed/fixtures": "./dist/seed/fixtures.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/policy-safe-knowledge-assistant"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './policy-safe-knowledge-assistant.docblock';

package/src/docs/policy-safe-knowledge-assistant.docblock.ts

@@ -0,0 +1,28 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const docBlocks: DocBlock[] = [
+  {
+    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\n- Assistant answers are structured and must cite a KB snapshot (or refuse).\n- Locale + jurisdiction are mandatory inputs for every assistant call.\n- Automation proposes KB patches; humans verify; publishing stays blocked until approvals.\n- Learning hub demonstrates drills + coaching + quests without spam.\n\n## Offline-first\n- Seeded fixtures are deterministic and require no external services.\n- 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)\n1) Onboard: set locale + jurisdiction.\n2) Publish snapshot: ingest source -> propose rule -> approve -> publish.\n3) Ask assistant: must pass gate and cite snapshot.\n4) Simulate change: watcher -> review -> publish new snapshot.\n5) Learning hub: drills session, ambient tip, quest start + step completion.`,
+  },
+];
+
+registerDocBlocks(docBlocks);

package/src/example.ts

@@ -0,0 +1,36 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const 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 },
+  },
+});
+
+export default example;

package/src/handlers/index.ts

@@ -0,0 +1 @@
+export * from './policy-safe-knowledge-assistant.handlers';