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

package/src/orchestrator/buildAnswer.ts

@@ -0,0 +1,122 @@
+import {
+  enforceAllowedScope,
+  enforceCitations,
+  validateEnvelope,
+} from '@contractspec/example.locale-jurisdiction-gate/policy/guard';
+
+type AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';
+
+export interface AssistantAnswerIR {
+  locale: string;
+  jurisdiction: string;
+  allowedScope: AllowedScope;
+  sections: { heading: string; body: string }[];
+  citations: {
+    kbSnapshotId: string;
+    sourceType: string;
+    sourceId: string;
+    title?: string;
+    excerpt?: string;
+  }[];
+  disclaimers?: string[];
+  riskFlags?: string[];
+  refused?: boolean;
+  refusalReason?: string;
+}
+
+export interface BuildAnswerInput {
+  envelope: {
+    traceId: string;
+    locale: string;
+    kbSnapshotId: string;
+    allowedScope: AllowedScope;
+    regulatoryContext: { jurisdiction: string };
+  };
+  question: string;
+  kbSearch: (input: {
+    snapshotId: string;
+    jurisdiction: string;
+    query: string;
+  }) => Promise<{ items: { ruleVersionId: string; excerpt?: string }[] }>;
+}
+
+/**
+ * Build a policy-safe assistant answer derived from KB search results.
+ *
+ * Deterministic: no LLM calls; if search yields no results, it refuses.
+ */
+export async function buildPolicySafeAnswer(
+  input: BuildAnswerInput
+): Promise<AssistantAnswerIR> {
+  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: AssistantAnswerIR = {
+    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;
+}

package/src/policy-safe-knowledge-assistant.feature.ts

@@ -0,0 +1,58 @@
+import { defineFeature } from '@contractspec/lib.contracts';
+
+export const 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: [
+    // Gate
+    { key: 'assistant.answer', version: '1.0.0' },
+    { key: 'assistant.explainConcept', version: '1.0.0' },
+    // KB
+    { 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' },
+    // Pipeline
+    { 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' },
+    ],
+  },
+});

package/src/seed/fixtures.ts

@@ -0,0 +1,31 @@
+export const DEMO_FIXTURES = {
+  jurisdictions: ['EU', 'FR'] as const,
+  locales: ['en-GB', 'fr-FR'] as const,
+  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',
+    },
+  },
+} as const;

package/src/seed/index.ts

@@ -0,0 +1 @@
+export * from './fixtures';

package/src/seeders/index.ts

@@ -0,0 +1,20 @@
+import type { DatabasePort } from '@contractspec/lib.runtime-sandbox';
+
+export async function seedPolicyKnowledgeAssistant(params: {
+  projectId: string;
+  db: DatabasePort;
+}) {
+  const { projectId, db } = params;
+
+  const existing = await db.query(
+    `SELECT COUNT(*) as count FROM psa_user_context WHERE "projectId" = $1`,
+    [projectId]
+  );
+  if ((existing.rows[0]?.count as number) > 0) return;
+
+  await db.execute(
+    `INSERT INTO psa_user_context ("projectId", locale, jurisdiction, "allowedScope")
+     VALUES ($1, $2, $3, $4)`,
+    [projectId, 'en-GB', 'EU', 'education_only']
+  );
+}

package/src/ui/PolicySafeKnowledgeAssistantDashboard.tsx

@@ -0,0 +1,206 @@
+'use client';
+
+import { useCallback, useMemo, useState } 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 { usePolicySafeKnowledgeAssistant } from './hooks/usePolicySafeKnowledgeAssistant';
+
+type AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';
+
+export function PolicySafeKnowledgeAssistantDashboard() {
+  const { state, actions } = usePolicySafeKnowledgeAssistant();
+  const [question, setQuestion] = useState('reporting obligations');
+  const [content, setContent] = useState(
+    'EU: Reporting obligations v2 (updated)'
+  );
+  const [locale, setLocale] = useState('en-GB');
+  const [jurisdiction, setJurisdiction] = useState('EU');
+  const [allowedScope, setAllowedScope] =
+    useState<AllowedScope>('education_only');
+
+  const snapshotId =
+    state.context?.kbSnapshotId ?? state.lastSnapshotId ?? null;
+
+  const stats = useMemo(() => {
+    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 = useCallback(async () => {
+    await actions.setContext({ locale, jurisdiction, allowedScope });
+  }, [actions, allowedScope, jurisdiction, locale]);
+
+  const handleAsk = useCallback(async () => {
+    await actions.askAssistant(question);
+  }, [actions, question]);
+
+  const handleAdminPublishFlow = useCallback(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 <LoaderBlock label="Loading demo..." />;
+  }
+
+  if (state.error) {
+    return (
+      <ErrorState
+        title="Failed to load demo"
+        description={state.error.message}
+        onRetry={actions.refreshContext}
+        retryLabel="Retry"
+      />
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      <StatCardGroup>
+        {stats.map((s) => (
+          <StatCard key={s.label} label={s.label} value={String(s.value)} />
+        ))}
+      </StatCardGroup>
+
+      <Card className="p-4">
+        <h3 className="text-lg font-semibold">
+          1) Onboarding (explicit locale + jurisdiction)
+        </h3>
+        <div className="mt-3 grid gap-3 md:grid-cols-3">
+          <div>
+            <div className="text-muted-foreground mb-1 text-xs font-semibold tracking-wide uppercase">
+              Locale
+            </div>
+            <Input value={locale} onChange={(e) => setLocale(e.target.value)} />
+          </div>
+          <div>
+            <div className="text-muted-foreground mb-1 text-xs font-semibold tracking-wide uppercase">
+              Jurisdiction
+            </div>
+            <Input
+              value={jurisdiction}
+              onChange={(e) => setJurisdiction(e.target.value)}
+            />
+          </div>
+          <div>
+            <div className="text-muted-foreground mb-1 text-xs font-semibold tracking-wide uppercase">
+              Allowed scope
+            </div>
+            <Select
+              value={allowedScope}
+              onValueChange={(v) => setAllowedScope(v as AllowedScope)}
+            >
+              <SelectTrigger>
+                <SelectValue placeholder="Select scope" />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="education_only">education_only</SelectItem>
+                <SelectItem value="generic_info">generic_info</SelectItem>
+                <SelectItem value="escalation_required">
+                  escalation_required
+                </SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+        </div>
+        <div className="mt-4 flex gap-2">
+          <Button onPress={handleSetContext}>Save context</Button>
+          <Button variant="outline" onPress={actions.refreshContext}>
+            Refresh
+          </Button>
+        </div>
+      </Card>
+
+      <Card className="p-4">
+        <h3 className="text-lg font-semibold">
+          2) Ask the assistant (must cite KB snapshot)
+        </h3>
+        <div className="mt-3 flex flex-col gap-3">
+          <Input
+            value={question}
+            onChange={(e) => setQuestion(e.target.value)}
+          />
+          <div className="flex gap-2">
+            <Button onPress={handleAsk}>Ask</Button>
+          </div>
+        </div>
+
+        {state.lastAnswer ? (
+          <div className="mt-4 space-y-3">
+            {state.lastAnswer.refused ? (
+              <div className="text-sm text-red-600">
+                Refused: {state.lastAnswer.refusalReason ?? 'UNKNOWN'}
+              </div>
+            ) : null}
+            {state.lastAnswer.sections.map((s, idx) => (
+              <div key={`${s.heading}-${idx}`}>
+                <div className="text-sm font-semibold">{s.heading}</div>
+                <div className="text-muted-foreground text-sm">{s.body}</div>
+              </div>
+            ))}
+            <div className="text-sm font-semibold">Citations</div>
+            <ul className="text-muted-foreground list-disc pl-5 text-sm">
+              {state.lastAnswer.citations.map((c) => (
+                <li key={`${c.kbSnapshotId}-${c.sourceId}`}>
+                  {c.kbSnapshotId} — {c.sourceId}
+                </li>
+              ))}
+            </ul>
+          </div>
+        ) : null}
+      </Card>
+
+      <Card className="p-4">
+        <h3 className="text-lg font-semibold">
+          3) Admin: publish a new snapshot (HITL)
+        </h3>
+        <div className="mt-3 space-y-3">
+          <Textarea
+            value={content}
+            onChange={(e) => setContent(e.target.value)}
+          />
+          <Button onPress={handleAdminPublishFlow}>
+            Simulate change → review → approve → publish snapshot
+          </Button>
+        </div>
+      </Card>
+
+      <Card className="p-4">
+        <h3 className="text-lg font-semibold">4) Learning hub (patterns)</h3>
+        <p className="text-muted-foreground mt-2 text-sm">
+          This template includes drills, ambient coach, and quests as reusable
+          Learning Journey tracks. The interactive learning UI is demonstrated
+          in dedicated Learning Journey examples.
+        </p>
+      </Card>
+    </div>
+  );
+}

package/src/ui/hooks/usePolicySafeKnowledgeAssistant.ts

@@ -0,0 +1,229 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTemplateRuntime } from '@contractspec/lib.example-shared-ui';
+
+type AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';
+type RiskLevel = 'low' | 'medium' | 'high';
+
+export interface UsePolicySafeKnowledgeAssistantState {
+  context: {
+    locale: string;
+    jurisdiction: string;
+    allowedScope: AllowedScope;
+    kbSnapshotId: string | null;
+  } | null;
+  loading: boolean;
+  error: Error | null;
+  lastAnswer: {
+    refused?: boolean;
+    refusalReason?: string;
+    sections: { heading: string; body: string }[];
+    citations: {
+      kbSnapshotId: string;
+      sourceId: string;
+      excerpt?: string;
+    }[];
+  } | null;
+  lastRuleId: string | null;
+  lastRuleVersionId: string | null;
+  lastSnapshotId: string | null;
+  lastReviewTaskId: string | null;
+}
+
+interface CitationLike {
+  kbSnapshotId: string;
+  sourceId: string;
+  excerpt?: string;
+}
+interface AnswerLike {
+  refused?: boolean;
+  refusalReason?: string;
+  sections: { heading: string; body: string }[];
+  citations: CitationLike[];
+}
+
+function isCitationLike(value: unknown): value is CitationLike {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.kbSnapshotId === 'string' && typeof v.sourceId === 'string';
+}
+
+function toCitations(value: unknown): CitationLike[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter(isCitationLike).map((c) => ({
+    kbSnapshotId: c.kbSnapshotId,
+    sourceId: c.sourceId,
+    excerpt: c.excerpt,
+  }));
+}
+
+import type { PolicySafeKnowledgeAssistantHandlers } from '../../handlers/policy-safe-knowledge-assistant.handlers';
+
+export function usePolicySafeKnowledgeAssistant() {
+  const { handlers, projectId } = useTemplateRuntime<{
+    policySafeKnowledgeAssistant: PolicySafeKnowledgeAssistantHandlers;
+  }>();
+  const api = handlers.policySafeKnowledgeAssistant;
+
+  const [state, setState] = useState<UsePolicySafeKnowledgeAssistantState>({
+    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: {
+      locale: string;
+      jurisdiction: string;
+      allowedScope: AllowedScope;
+    }) => {
+      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: string) => {
+      const answerUnknown: unknown = await api.answer({ projectId, question });
+      const answer = answerUnknown as AnswerLike;
+      setState((s) => ({
+        ...s,
+        lastAnswer: {
+          refused: answer.refused,
+          refusalReason: answer.refusalReason,
+          sections: answer.sections,
+          citations: toCitations(
+            (answerUnknown as { citations?: unknown }).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 as string;
+  }, [api, projectId, state.context?.jurisdiction]);
+
+  const upsertRuleVersion = useCallback(
+    async (input: { ruleId: string; content: string }) => {
+      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 as string;
+    },
+    [api, projectId]
+  );
+
+  const approveRuleVersion = useCallback(
+    async (ruleVersionId: string) => {
+      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 as string;
+  }, [api, projectId, refreshContext, state.context?.jurisdiction]);
+
+  const simulateHighRiskChangeAndApprove = useCallback(
+    async (ruleVersionId: string) => {
+      const cand = await api.createChangeCandidate({
+        projectId,
+        jurisdiction: state.context?.jurisdiction ?? 'EU',
+        diffSummary: 'Simulated change (demo)',
+        riskLevel: 'high' satisfies RiskLevel,
+        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 as string;
+    },
+    [api, projectId, state.context?.jurisdiction]
+  );
+
+  const derived = useMemo(() => ({ projectId }), [projectId]);
+
+  return {
+    state,
+    derived,
+    actions: {
+      refreshContext,
+      setContext,
+      askAssistant,
+      createDemoRule,
+      upsertRuleVersion,
+      approveRuleVersion,
+      publishSnapshot,
+      simulateHighRiskChangeAndApprove,
+    },
+  };
+}

package/src/ui/index.ts

@@ -0,0 +1 @@
+export * from './PolicySafeKnowledgeAssistantDashboard';

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+
+
+
+
+
+
+
+
+
+