@contractspec/example.locale-jurisdiction-gate 1.44.0

package/src/operations/assistant.ts

@@ -0,0 +1,98 @@
+import { defineCommand } from '@contractspec/lib.contracts';
+import { ScalarTypeEnum, defineSchemaModel } from '@contractspec/lib.schema';
+
+import {
+  AssistantAnswerIRModel,
+  LLMCallEnvelopeModel,
+} from '../entities/models';
+
+const AssistantQuestionInput = defineSchemaModel({
+  name: 'AssistantQuestionInput',
+  description: 'Input for assistant calls with mandatory envelope.',
+  fields: {
+    envelope: { type: LLMCallEnvelopeModel, isOptional: false },
+    question: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+const AssistantConceptInput = defineSchemaModel({
+  name: 'AssistantConceptInput',
+  description: 'Input for explaining a concept with mandatory envelope.',
+  fields: {
+    envelope: { type: LLMCallEnvelopeModel, isOptional: false },
+    conceptKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const AssistantAnswerContract = defineCommand({
+  meta: {
+    key: 'assistant.answer',
+    version: 1,
+    stability: 'experimental',
+    owners: ['@examples'],
+    tags: ['assistant', 'policy', 'locale', 'jurisdiction', 'knowledge'],
+    description:
+      'Answer a user question using a KB snapshot with strict locale/jurisdiction gating.',
+    goal: 'Provide policy-safe answers that cite a KB snapshot or refuse.',
+    context:
+      'Called by UI or workflows; must fail-closed if envelope is invalid or citations are missing.',
+  },
+  io: {
+    input: AssistantQuestionInput,
+    output: AssistantAnswerIRModel,
+    errors: {
+      LOCALE_REQUIRED: {
+        description: 'Locale is required and must be supported',
+        http: 400,
+        gqlCode: 'LOCALE_REQUIRED',
+        when: 'locale is missing or unsupported',
+      },
+      JURISDICTION_REQUIRED: {
+        description: 'Jurisdiction is required',
+        http: 400,
+        gqlCode: 'JURISDICTION_REQUIRED',
+        when: 'jurisdiction is missing',
+      },
+      KB_SNAPSHOT_REQUIRED: {
+        description: 'KB snapshot id is required',
+        http: 400,
+        gqlCode: 'KB_SNAPSHOT_REQUIRED',
+        when: 'kbSnapshotId is missing',
+      },
+      CITATIONS_REQUIRED: {
+        description: 'Answers must include citations to a KB snapshot',
+        http: 422,
+        gqlCode: 'CITATIONS_REQUIRED',
+        when: 'answer has no citations',
+      },
+      SCOPE_VIOLATION: {
+        description:
+          'Answer violates allowed scope and must be refused/escalated',
+        http: 403,
+        gqlCode: 'SCOPE_VIOLATION',
+        when: 'output includes forbidden content under the given allowedScope',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+});
+
+export const AssistantExplainConceptContract = defineCommand({
+  meta: {
+    key: 'assistant.explainConcept',
+    version: 1,
+    stability: 'experimental',
+    owners: ['@examples'],
+    tags: ['assistant', 'policy', 'knowledge', 'concepts'],
+    description:
+      'Explain a concept using a KB snapshot with strict locale/jurisdiction gating.',
+    goal: 'Explain concepts with citations or refuse.',
+    context: 'Same constraints as assistant.answer.',
+  },
+  io: {
+    input: AssistantConceptInput,
+    output: AssistantAnswerIRModel,
+    errors: AssistantAnswerContract.io.errors,
+  },
+  policy: { auth: 'user' },
+});

package/src/operations/index.ts

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

package/src/policy/guard.test.ts

@@ -0,0 +1,25 @@
+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,102 @@
+import type { GateError, GateResult } from './types';
+
+interface EnvelopeLike {
+  locale?: string;
+  kbSnapshotId?: string;
+  allowedScope?: 'education_only' | 'generic_info' | 'escalation_required';
+  regulatoryContext?: { jurisdiction?: string };
+}
+
+interface AnswerLike {
+  citations?: unknown[];
+  sections?: { 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,2 @@
+export * from './types';
+export * from './guard';

package/src/policy/types.ts

@@ -0,0 +1,18 @@
+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,17 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+
+
+
+
+
+
+
+