@contractspec/example.policy-safe-knowledge-assistant 1.44.0

package/src/integration.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  createMemoryKbHandlers,
+  createMemoryKbStore,
+} from '@contractspec/example.versioned-knowledge-base/handlers/memory.handlers';
+import {
+  createPipelineMemoryHandlers,
+  createPipelineMemoryStore,
+} from '@contractspec/example.kb-update-pipeline/handlers/memory.handlers';
+
+import { buildPolicySafeAnswer } from './orchestrator/buildAnswer';
+import { DEMO_FIXTURES } from './seed/fixtures';
+
+describe('@contractspec/example.policy-safe-knowledge-assistant integration', () => {
+  it('answers cite latest snapshot; after pipeline change + publish, answers cite new snapshot', async () => {
+    const kbStore = createMemoryKbStore();
+    const kb = createMemoryKbHandlers(kbStore);
+
+    const pipelineStore = createPipelineMemoryStore();
+    const pipeline = createPipelineMemoryHandlers(pipelineStore);
+
+    // Seed rules
+    await kb.createRule(DEMO_FIXTURES.rules.EU_RULE_TAX);
+
+    // Publish initial snapshot (EU v1)
+    const rv1 = await kb.upsertRuleVersion({
+      ruleId: DEMO_FIXTURES.rules.EU_RULE_TAX.id,
+      content: 'EU: Reporting obligations v1',
+      sourceRefs: [{ sourceDocumentId: 'src_eu_v1', excerpt: 'v1 excerpt' }],
+    });
+    await kb.approveRuleVersion({
+      ruleVersionId: rv1.id,
+      approver: 'expert_1',
+    });
+    const snap1 = await kb.publishSnapshot({
+      jurisdiction: 'EU',
+      asOfDate: new Date('2026-01-01T00:00:00.000Z'),
+    });
+
+    const envelopeBase = {
+      traceId: 'trace_1',
+      locale: 'en-GB',
+      regulatoryContext: { jurisdiction: 'EU' },
+      allowedScope: 'education_only' as const,
+    };
+
+    const a1 = await buildPolicySafeAnswer({
+      envelope: { ...envelopeBase, kbSnapshotId: snap1.id },
+      question: 'reporting obligations',
+      kbSearch: kb.search,
+    });
+
+    expect(a1.refused).not.toBeTrue();
+    expect(a1.citations.length).toBeGreaterThan(0);
+    expect(a1.citations[0]?.kbSnapshotId).toBe(snap1.id);
+
+    // Simulate regulatory change via pipeline: create candidate, review, propose patch
+    pipelineStore.candidates.set('cand_1', {
+      id: 'cand_1',
+      sourceDocumentId: 'EU_src_change',
+      detectedAt: new Date('2026-02-01T00:00:00.000Z'),
+      diffSummary: 'Updated obligations',
+      riskLevel: 'high',
+    });
+    const review = await pipeline.createReviewTask({
+      changeCandidateId: 'cand_1',
+    });
+    await pipeline.submitDecision({
+      reviewTaskId: review.id,
+      decision: 'approve',
+      decidedBy: 'expert_2',
+      decidedByRole: 'expert',
+    });
+
+    // Create + approve new KB rule version
+    const rv2 = await kb.upsertRuleVersion({
+      ruleId: DEMO_FIXTURES.rules.EU_RULE_TAX.id,
+      content: 'EU: Reporting obligations v2 (updated)',
+      sourceRefs: [{ sourceDocumentId: 'src_eu_v2', excerpt: 'v2 excerpt' }],
+    });
+    await kb.approveRuleVersion({
+      ruleVersionId: rv2.id,
+      approver: 'expert_2',
+    });
+
+    // Link pipeline proposal to the actual KB rule version id, then mark it approved
+    await pipeline.proposeRulePatch({
+      changeCandidateId: 'cand_1',
+      proposedRuleVersionIds: [rv2.id],
+    });
+    await pipeline.markRuleVersionApproved({ ruleVersionId: rv2.id });
+    await pipeline.publishIfReady({ jurisdiction: 'EU' });
+
+    const snap2 = await kb.publishSnapshot({
+      jurisdiction: 'EU',
+      asOfDate: new Date('2026-02-01T00:00:00.000Z'),
+    });
+
+    const a2 = await buildPolicySafeAnswer({
+      envelope: { ...envelopeBase, kbSnapshotId: snap2.id },
+      question: 'updated obligations',
+      kbSearch: kb.search,
+    });
+    expect(a2.refused).not.toBeTrue();
+    expect(a2.citations[0]?.kbSnapshotId).toBe(snap2.id);
+  });
+});

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/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/tsconfig.json

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