@lssm/example.locale-jurisdiction-gate 0.0.0-canary-20251213172311

package/src/handlers/demo.handlers.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createDemoAssistantHandlers } from './demo.handlers';
+
+describe('@lssm/example.locale-jurisdiction-gate demo handlers', () => {
+  it('blocks when locale is missing', async () => {
+    const handlers = createDemoAssistantHandlers();
+    const result = await handlers.answer({
+      envelope: {
+        traceId: 't1',
+        locale: '',
+        kbSnapshotId: 'snap_1',
+        allowedScope: 'education_only',
+        regulatoryContext: { jurisdiction: 'EU' },
+      },
+      question: 'What is a snapshot?',
+    });
+    expect(result.refused).toBeTrue();
+    expect(result.refusalReason).toBe('LOCALE_REQUIRED');
+  });
+
+  it('blocks when kbSnapshotId is missing', async () => {
+    const handlers = createDemoAssistantHandlers();
+    const result = await handlers.answer({
+      envelope: {
+        traceId: 't2',
+        locale: 'en-GB',
+        kbSnapshotId: '',
+        allowedScope: 'education_only',
+        regulatoryContext: { jurisdiction: 'EU' },
+      },
+      question: 'What is a snapshot?',
+    });
+    expect(result.refused).toBeTrue();
+    expect(result.refusalReason).toBe('KB_SNAPSHOT_REQUIRED');
+  });
+
+  it('blocks education_only answers that include buy/sell language', async () => {
+    const handlers = createDemoAssistantHandlers();
+    const result = await handlers.answer({
+      envelope: {
+        traceId: 't3',
+        locale: 'en-GB',
+        kbSnapshotId: 'snap_1',
+        allowedScope: 'education_only',
+        regulatoryContext: { jurisdiction: 'EU' },
+      },
+      question: 'Should I buy now?',
+    });
+    // demo handler echoes question; question includes forbidden phrase \"buy\"
+    expect(result.refused).toBeTrue();
+    expect(result.refusalReason).toBe('SCOPE_VIOLATION');
+  });
+});

package/src/handlers/demo.handlers.ts

@@ -0,0 +1,154 @@
+import { enforceAllowedScope, enforceCitations, validateEnvelope } from '../policy/guard';
+
+type AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';
+
+type AssistantAnswerIR = {
+  locale: string;
+  jurisdiction: string;
+  allowedScope: AllowedScope;
+  sections: Array<{ heading: string; body: string }>;
+  citations: Array<{
+    kbSnapshotId: string;
+    sourceType: string;
+    sourceId: string;
+    title?: string;
+    excerpt?: string;
+  }>;
+  disclaimers?: string[];
+  riskFlags?: string[];
+  refused?: boolean;
+  refusalReason?: string;
+};
+
+export interface DemoAssistantHandlers {
+  answer(input: {
+    envelope: {
+      traceId: string;
+      locale: string;
+      kbSnapshotId: string;
+      allowedScope: AllowedScope;
+      regulatoryContext: { jurisdiction: string };
+    };
+    question: string;
+  }): Promise<AssistantAnswerIR>;
+
+  explainConcept(input: {
+    envelope: {
+      traceId: string;
+      locale: string;
+      kbSnapshotId: string;
+      allowedScope: AllowedScope;
+      regulatoryContext: { jurisdiction: string };
+    };
+    conceptKey: string;
+  }): Promise<AssistantAnswerIR>;
+}
+
+/**
+ * Deterministic demo assistant handlers (no LLM).
+ *
+ * - Validates envelope
+ * - Requires citations
+ * - Enforces allowedScope (education_only blocks actionable language)
+ */
+export function createDemoAssistantHandlers(): DemoAssistantHandlers {
+  async function answer(input: {
+    envelope: DemoAssistantHandlers['answer'] extends (a: infer A) => any
+      ? A extends { envelope: infer E }
+        ? E
+        : never
+      : never;
+    question: string;
+  }): Promise<AssistantAnswerIR> {
+    const env = validateEnvelope(input.envelope);
+    if (!env.ok) {
+      return {
+        locale: input.envelope.locale ?? 'en-US',
+        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 draft: AssistantAnswerIR = {
+      locale: env.value.locale,
+      jurisdiction: env.value.regulatoryContext!.jurisdiction!,
+      allowedScope: env.value.allowedScope!,
+      sections: [
+        {
+          heading: 'Answer (demo)',
+          body: `You asked: "${input.question}". This demo answer is derived from the KB snapshot only.`,
+        },
+      ],
+      citations: [
+        {
+          kbSnapshotId: env.value.kbSnapshotId!,
+          sourceType: 'ruleVersion',
+          sourceId: 'rv_demo',
+          title: 'Demo rule version',
+          excerpt: 'Demo excerpt',
+        },
+      ],
+      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 },
+        ],
+        citations: draft.citations,
+        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;
+  }
+
+  async function explainConcept(input: {
+    envelope: DemoAssistantHandlers['explainConcept'] extends (a: infer A) => any
+      ? A extends { envelope: infer E }
+        ? E
+        : never
+      : never;
+    conceptKey: string;
+  }): Promise<AssistantAnswerIR> {
+    return await answer({
+      envelope: input.envelope,
+      question: `Explain concept: ${input.conceptKey}`,
+    });
+  }
+
+  return { answer, explainConcept };
+}
+
+

package/src/handlers/index.ts

@@ -0,0 +1,3 @@
+export * from './demo.handlers';
+
+

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Locale/Jurisdiction Gate Example
+ *
+ * Fail-closed gating for assistant calls: locale + jurisdiction + kbSnapshotId +
+ * allowedScope must be explicit, and answers must cite a KB snapshot.
+ */
+export * from './entities';
+export * from './contracts';
+export * from './events';
+export * from './policy';
+export * from './handlers';
+export * from './feature';
+export { default as example } from './example';
+
+import './docs';
+
+

package/src/policy/guard.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'bun:test';
+
+import { enforceCitations, validateEnvelope } from './guard';
+
+describe('locale/jurisdiction gate policy', () => {
+  it('blocks unsupported locale', () => {
+    const result = validateEnvelope({
+      locale: 'es-ES',
+      kbSnapshotId: 'snap_1',
+      allowedScope: 'education_only',
+      regulatoryContext: { jurisdiction: 'EU' },
+    });
+    expect(result.ok).toBeFalse();
+    if (!result.ok) expect(result.error.code).toBe('LOCALE_REQUIRED');
+  });
+
+  it('blocks answer without citations', () => {
+    const result = enforceCitations({
+      sections: [{ heading: 'A', body: 'B' }],
+      citations: [],
+    });
+    expect(result.ok).toBeFalse();
+    if (!result.ok) expect(result.error.code).toBe('CITATIONS_REQUIRED');
+  });
+});
+
+

package/src/policy/guard.ts

@@ -0,0 +1,96 @@
+import type { GateError, GateResult } from './types';
+
+type EnvelopeLike = {
+  locale?: string;
+  kbSnapshotId?: string;
+  allowedScope?: 'education_only' | 'generic_info' | 'escalation_required';
+  regulatoryContext?: { jurisdiction?: string };
+};
+
+type AnswerLike = {
+  citations?: unknown[];
+  sections?: Array<{ heading: string; body: string }>;
+  refused?: boolean;
+  refusalReason?: string;
+  allowedScope?: 'education_only' | 'generic_info' | 'escalation_required';
+};
+
+const SUPPORTED_LOCALES = new Set<string>(['en-US', 'en-GB', 'fr-FR']);
+
+function err(code: GateError['code'], message: string): GateError {
+  return { code, message };
+}
+
+export function validateEnvelope(
+  envelope: EnvelopeLike
+): GateResult<Required<EnvelopeLike>> {
+  if (!envelope.locale || !SUPPORTED_LOCALES.has(envelope.locale)) {
+    return {
+      ok: false,
+      error: err('LOCALE_REQUIRED', 'locale is required and must be supported'),
+    };
+  }
+  if (!envelope.regulatoryContext?.jurisdiction) {
+    return { ok: false, error: err('JURISDICTION_REQUIRED', 'jurisdiction is required') };
+  }
+  if (!envelope.kbSnapshotId) {
+    return {
+      ok: false,
+      error: err('KB_SNAPSHOT_REQUIRED', 'kbSnapshotId is required'),
+    };
+  }
+  if (!envelope.allowedScope) {
+    return {
+      ok: false,
+      error: err('SCOPE_VIOLATION', 'allowedScope is required'),
+    };
+  }
+  return { ok: true, value: envelope as Required<EnvelopeLike> };
+}
+
+export function enforceCitations(answer: AnswerLike): GateResult<AnswerLike> {
+  const citations = answer.citations ?? [];
+  if (!Array.isArray(citations) || citations.length === 0) {
+    return {
+      ok: false,
+      error: err('CITATIONS_REQUIRED', 'answers must include at least one citation'),
+    };
+  }
+  return { ok: true, value: answer };
+}
+
+const EDUCATION_ONLY_FORBIDDEN_PATTERNS: RegExp[] = [
+  /\b(buy|sell)\b/i,
+  /\b(should\s+buy|should\s+sell)\b/i,
+  /\b(guarantee(d)?|promise(d)?)\b/i,
+];
+
+export function enforceAllowedScope(
+  allowedScope: EnvelopeLike['allowedScope'],
+  answer: AnswerLike
+): GateResult<AnswerLike> {
+  if (!allowedScope) {
+    return {
+      ok: false,
+      error: err('SCOPE_VIOLATION', 'allowedScope is required'),
+    };
+  }
+  if (allowedScope !== 'education_only') {
+    return { ok: true, value: answer };
+  }
+
+  const bodies = (answer.sections ?? []).map((s) => s.body).join('\n');
+  const violations = EDUCATION_ONLY_FORBIDDEN_PATTERNS.some((re) => re.test(bodies));
+  if (violations) {
+    return {
+      ok: false,
+      error: err(
+        'SCOPE_VIOLATION',
+        'answer violates education_only scope (contains actionable or promotional language)'
+      ),
+    };
+  }
+  return { ok: true, value: answer };
+}
+
+

package/src/policy/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './guard';
+
+

package/src/policy/types.ts

@@ -0,0 +1,17 @@
+export type AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';
+
+export interface GateError {
+  code:
+    | 'LOCALE_REQUIRED'
+    | 'JURISDICTION_REQUIRED'
+    | 'KB_SNAPSHOT_REQUIRED'
+    | 'CITATIONS_REQUIRED'
+    | 'SCOPE_VIOLATION';
+  message: string;
+}
+
+export type GateResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: GateError };
+
+

package/tsconfig.json

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