@contractspec/example.locale-jurisdiction-gate 3.7.6 → 3.7.10

package/src/handlers/demo.handlers.ts

@@ -1,51 +1,51 @@
 import {
-  enforceAllowedScope,
-  enforceCitations,
-  validateEnvelope,
+	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;
+	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>;
+	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>;
+	explainConcept(input: {
+		envelope: {
+			traceId: string;
+			locale: string;
+			kbSnapshotId: string;
+			allowedScope: AllowedScope;
+			regulatoryContext: { jurisdiction: string };
+		};
+		conceptKey: string;
+	}): Promise<AssistantAnswerIR>;
 }
 
 /**
@@ -56,105 +56,105 @@ export interface DemoAssistantHandlers {
  * - 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,
-      };
-    }
+	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 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 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],
-      };
-    }
+		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;
-  }
+		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}`,
-    });
-  }
+	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 };
+	return { answer, explainConcept };
 }

package/src/index.ts

@@ -5,11 +5,13 @@
  * allowedScope must be explicit, and answers must cite a KB snapshot.
  */
 export * from './entities';
-export * from './operations';
 export * from './events';
-export * from './policy';
+export { default as example } from './example';
+export * from './forms';
 export * from './handlers';
 export * from './locale-jurisdiction-gate.feature';
-export { default as example } from './example';
+export * from './operations';
+export * from './policy';
+export * from './translations';
 
 import './docs';

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

@@ -1,41 +1,47 @@
 import { defineFeature } from '@contractspec/lib.contracts-spec';
+import { AssistantGatePolicy } from './policy/assistant-gate.policy';
 
 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' }],
-  },
+	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' }],
+	},
 
-  policies: [{ key: 'locale-jurisdiction-gate.policy.gate', version: '1.0.0' }],
+	policies: [
+		{
+			key: AssistantGatePolicy.meta.key,
+			version: AssistantGatePolicy.meta.version,
+		},
+	],
 
-  knowledge: [
-    { key: 'locale-jurisdiction-gate.knowledge.rules', version: '1.0.0' },
-  ],
+	knowledge: [
+		{ key: 'locale-jurisdiction-gate.knowledge.rules', version: '1.0.0' },
+	],
 
-  docs: [
-    'docs.examples.locale-jurisdiction-gate.goal',
-    'docs.examples.locale-jurisdiction-gate.reference',
-  ],
+	docs: [
+		'docs.examples.locale-jurisdiction-gate.goal',
+		'docs.examples.locale-jurisdiction-gate.reference',
+	],
 });

package/src/operations/assistant.ts

@@ -1,98 +1,98 @@
 import { defineCommand } from '@contractspec/lib.contracts-spec';
-import { ScalarTypeEnum, defineSchemaModel } from '@contractspec/lib.schema';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
 
 import {
-  AssistantAnswerIRModel,
-  LLMCallEnvelopeModel,
+	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 },
-  },
+	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 },
-  },
+	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' },
+	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' },
+	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/policy/assistant-gate.policy.ts

@@ -0,0 +1,65 @@
+import {
+	OwnersEnum,
+	StabilityEnum,
+	TagsEnum,
+} from '@contractspec/lib.contracts-spec/ownership';
+import { definePolicy } from '@contractspec/lib.contracts-spec/policy';
+
+export const AssistantGatePolicy = definePolicy({
+	meta: {
+		key: 'locale-jurisdiction-gate.policy.gate',
+		version: '1.0.0',
+		title: 'Assistant Locale and Jurisdiction Gate',
+		description:
+			'Requires explicit locale, jurisdiction, knowledge snapshot, and allowed scope before assistant requests may proceed.',
+		domain: 'assistant',
+		scope: 'operation',
+		owners: [OwnersEnum.PlatformFinance],
+		tags: [TagsEnum.I18n, 'assistant', 'policy', 'jurisdiction'],
+		stability: StabilityEnum.Experimental,
+	},
+	rules: [
+		{
+			effect: 'deny',
+			actions: ['assistant.answer', 'assistant.explainConcept'],
+			resource: { type: 'assistant-call' },
+			conditions: [
+				{
+					expression:
+						'!context.locale || !context.jurisdiction || !context.kbSnapshotId || !context.allowedScope',
+				},
+			],
+			reason:
+				'Assistant requests fail closed until locale, jurisdiction, kbSnapshotId, and allowedScope are explicit.',
+		},
+		{
+			effect: 'deny',
+			actions: ['assistant.answer', 'assistant.explainConcept'],
+			resource: { type: 'assistant-call' },
+			conditions: [
+				{
+					expression:
+						"!['en-US', 'en-GB', 'fr-FR'].includes(context.locale ?? '')",
+				},
+			],
+			reason: 'Only the explicitly reviewed assistant locales are permitted.',
+		},
+		{
+			effect: 'allow',
+			actions: ['assistant.answer', 'assistant.explainConcept'],
+			resource: { type: 'assistant-call' },
+			conditions: [
+				{
+					expression:
+						"['en-US', 'en-GB', 'fr-FR'].includes(context.locale ?? '') && !!context.jurisdiction && !!context.kbSnapshotId && !!context.allowedScope",
+				},
+			],
+			reason:
+				'Explicit context is present, so the request may continue to citation and scope validation.',
+		},
+	],
+	pii: {
+		fields: ['kbSnapshotId'],
+		retentionDays: 30,
+	},
+});