@contractspec/example.locale-jurisdiction-gate 0.0.0-canary-20260113162409

package/src/handlers/demo.handlers.ts

@@ -0,0 +1,160 @@
+import {
+  enforceAllowedScope,
+  enforceCitations,
+  validateEnvelope,
+} from '../policy/guard';
+
+type AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';
+
+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 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: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    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 ?? 'UNKNOWN',
+      allowedScope: env.value.allowedScope ?? 'education_only',
+      sections: [
+        {
+          heading: 'Answer (demo)',
+          body: `You asked: "${input.question}". This demo answer is derived from the KB snapshot only.`,
+        },
+      ],
+      citations: [
+        {
+          kbSnapshotId: env.value.kbSnapshotId ?? 'unknown',
+          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 // eslint-disable-line @typescript-eslint/no-explicit-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 @@
+export * from './demo.handlers';

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 './operations';
+export * from './events';
+export * from './policy';
+export * from './handlers';
+export * from './locale-jurisdiction-gate.feature';
+export { default as example } from './example';
+
+import './docs';

package/src/locale-jurisdiction-gate.feature.ts

@@ -0,0 +1,30 @@
+import { defineFeature } from '@contractspec/lib.contracts';
+
+export const LocaleJurisdictionGateFeature = defineFeature({
+  meta: {
+    key: 'locale-jurisdiction-gate',
+    version: '1.0.0',
+    title: 'Locale + Jurisdiction Gate',
+    description:
+      'Fail-closed gating for assistant calls requiring locale/jurisdiction/snapshot/scope and citations.',
+    domain: 'knowledge',
+    owners: ['@examples'],
+    tags: ['assistant', 'policy', 'locale', 'jurisdiction', 'knowledge'],
+    stability: 'experimental',
+  },
+  operations: [
+    { key: 'assistant.answer', version: '1.0.0' },
+    { key: 'assistant.explainConcept', 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' },
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    requires: [{ key: 'knowledge', version: '1.0.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.0.0',
+    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.0.0',
+    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"]
+}
+
+
+
+
+
+
+
+