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

package/src/entities/models.ts

@@ -1,110 +1,110 @@
 import {
-  ScalarTypeEnum,
-  defineEnum,
-  defineSchemaModel,
+	defineEnum,
+	defineSchemaModel,
+	ScalarTypeEnum,
 } from '@contractspec/lib.schema';
 
 export const AllowedScopeEnum = defineEnum('AllowedScope', [
-  'education_only',
-  'generic_info',
-  'escalation_required',
+	'education_only',
+	'generic_info',
+	'escalation_required',
 ]);
 
 export const UserProfileModel = defineSchemaModel({
-  name: 'UserProfile',
-  description: 'User profile inputs used to derive regulatory context.',
-  fields: {
-    preferredLocale: {
-      type: ScalarTypeEnum.String_unsecure(),
-      isOptional: true,
-    },
-    residencyCountry: {
-      type: ScalarTypeEnum.String_unsecure(),
-      isOptional: true,
-    },
-    taxResidenceCountry: {
-      type: ScalarTypeEnum.String_unsecure(),
-      isOptional: true,
-    },
-    clientType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
-  },
+	name: 'UserProfile',
+	description: 'User profile inputs used to derive regulatory context.',
+	fields: {
+		preferredLocale: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+		},
+		residencyCountry: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+		},
+		taxResidenceCountry: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true,
+		},
+		clientType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+	},
 });
 
 export const RegulatoryContextModel = defineSchemaModel({
-  name: 'RegulatoryContext',
-  description: 'Explicit regulatory context (no guessing).',
-  fields: {
-    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    region: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
-    clientType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
-    allowedScope: { type: AllowedScopeEnum, isOptional: false },
-  },
+	name: 'RegulatoryContext',
+	description: 'Explicit regulatory context (no guessing).',
+	fields: {
+		jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		region: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+		clientType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+		allowedScope: { type: AllowedScopeEnum, isOptional: false },
+	},
 });
 
 export const LLMCallEnvelopeModel = defineSchemaModel({
-  name: 'LLMCallEnvelope',
-  description:
-    'Mandatory envelope for assistant calls. All fields are explicit and required for policy gating.',
-  fields: {
-    traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    locale: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    regulatoryContext: { type: RegulatoryContextModel, isOptional: false },
-    kbSnapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    allowedScope: { type: AllowedScopeEnum, isOptional: false },
-  },
+	name: 'LLMCallEnvelope',
+	description:
+		'Mandatory envelope for assistant calls. All fields are explicit and required for policy gating.',
+	fields: {
+		traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		locale: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		regulatoryContext: { type: RegulatoryContextModel, isOptional: false },
+		kbSnapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		allowedScope: { type: AllowedScopeEnum, isOptional: false },
+	},
 });
 
 export const AssistantCitationModel = defineSchemaModel({
-  name: 'AssistantCitation',
-  description:
-    'Citation referencing a KB snapshot + a specific item within it.',
-  fields: {
-    kbSnapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    sourceType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    sourceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
-    excerpt: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
-  },
+	name: 'AssistantCitation',
+	description:
+		'Citation referencing a KB snapshot + a specific item within it.',
+	fields: {
+		kbSnapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		sourceType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		sourceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		title: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+		excerpt: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+	},
 });
 
 export const AssistantAnswerSectionModel = defineSchemaModel({
-  name: 'AssistantAnswerSection',
-  description: 'Structured answer section.',
-  fields: {
-    heading: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    body: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-  },
+	name: 'AssistantAnswerSection',
+	description: 'Structured answer section.',
+	fields: {
+		heading: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		body: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+	},
 });
 
 export const AssistantAnswerIRModel = defineSchemaModel({
-  name: 'AssistantAnswerIR',
-  description:
-    'Structured assistant answer with mandatory citations and explicit locale/jurisdiction.',
-  fields: {
-    locale: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    allowedScope: { type: AllowedScopeEnum, isOptional: false },
-    sections: {
-      type: AssistantAnswerSectionModel,
-      isArray: true,
-      isOptional: false,
-    },
-    citations: {
-      type: AssistantCitationModel,
-      isArray: true,
-      isOptional: false,
-    },
-    disclaimers: {
-      type: ScalarTypeEnum.String_unsecure(),
-      isArray: true,
-      isOptional: true,
-    },
-    riskFlags: {
-      type: ScalarTypeEnum.String_unsecure(),
-      isArray: true,
-      isOptional: true,
-    },
-    refused: { type: ScalarTypeEnum.Boolean(), isOptional: true },
-    refusalReason: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
-  },
+	name: 'AssistantAnswerIR',
+	description:
+		'Structured assistant answer with mandatory citations and explicit locale/jurisdiction.',
+	fields: {
+		locale: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		allowedScope: { type: AllowedScopeEnum, isOptional: false },
+		sections: {
+			type: AssistantAnswerSectionModel,
+			isArray: true,
+			isOptional: false,
+		},
+		citations: {
+			type: AssistantCitationModel,
+			isArray: true,
+			isOptional: false,
+		},
+		disclaimers: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isArray: true,
+			isOptional: true,
+		},
+		riskFlags: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isArray: true,
+			isOptional: true,
+		},
+		refused: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+		refusalReason: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+	},
 });

package/src/events.ts

@@ -1,74 +1,74 @@
 import { defineEvent } from '@contractspec/lib.contracts-spec';
-import { ScalarTypeEnum, defineSchemaModel } from '@contractspec/lib.schema';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
 
 const AssistantAnswerRequestedPayload = defineSchemaModel({
-  name: 'AssistantAnswerRequestedPayload',
-  description: 'Emitted when an assistant answer is requested (pre-gate).',
-  fields: {
-    traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    locale: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    kbSnapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    allowedScope: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-  },
+	name: 'AssistantAnswerRequestedPayload',
+	description: 'Emitted when an assistant answer is requested (pre-gate).',
+	fields: {
+		traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		locale: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		kbSnapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		allowedScope: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+	},
 });
 
 export const AssistantAnswerRequestedEvent = defineEvent({
-  meta: {
-    key: 'assistant.answer.requested',
-    version: '1.0.0',
-    description: 'Assistant answer requested (policy gate will run).',
-    stability: 'experimental',
-    owners: ['@examples'],
-    tags: ['assistant', 'policy'],
-  },
-  payload: AssistantAnswerRequestedPayload,
+	meta: {
+		key: 'assistant.answer.requested',
+		version: '1.0.0',
+		description: 'Assistant answer requested (policy gate will run).',
+		stability: 'experimental',
+		owners: ['@examples'],
+		tags: ['assistant', 'policy'],
+	},
+	payload: AssistantAnswerRequestedPayload,
 });
 
 const AssistantAnswerBlockedPayload = defineSchemaModel({
-  name: 'AssistantAnswerBlockedPayload',
-  description: 'Emitted when a request is blocked by the gate.',
-  fields: {
-    traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    reasonCode: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-  },
+	name: 'AssistantAnswerBlockedPayload',
+	description: 'Emitted when a request is blocked by the gate.',
+	fields: {
+		traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		reasonCode: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+	},
 });
 
 export const AssistantAnswerBlockedEvent = defineEvent({
-  meta: {
-    key: 'assistant.answer.blocked',
-    version: '1.0.0',
-    description: 'Assistant answer blocked (fail-closed).',
-    stability: 'experimental',
-    owners: ['@examples'],
-    tags: ['assistant', 'policy', 'blocked'],
-  },
-  payload: AssistantAnswerBlockedPayload,
+	meta: {
+		key: 'assistant.answer.blocked',
+		version: '1.0.0',
+		description: 'Assistant answer blocked (fail-closed).',
+		stability: 'experimental',
+		owners: ['@examples'],
+		tags: ['assistant', 'policy', 'blocked'],
+	},
+	payload: AssistantAnswerBlockedPayload,
 });
 
 const AssistantAnswerDeliveredPayload = defineSchemaModel({
-  name: 'AssistantAnswerDeliveredPayload',
-  description: 'Emitted when a structured, cited answer is delivered.',
-  fields: {
-    traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    locale: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    kbSnapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    allowedScope: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
-    citationsCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
-  },
+	name: 'AssistantAnswerDeliveredPayload',
+	description: 'Emitted when a structured, cited answer is delivered.',
+	fields: {
+		traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		locale: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		kbSnapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		allowedScope: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		citationsCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+	},
 });
 
 export const AssistantAnswerDeliveredEvent = defineEvent({
-  meta: {
-    key: 'assistant.answer.delivered',
-    version: '1.0.0',
-    description:
-      'Assistant answer delivered (must include KB snapshot citations).',
-    stability: 'experimental',
-    owners: ['@examples'],
-    tags: ['assistant', 'policy', 'delivered'],
-  },
-  payload: AssistantAnswerDeliveredPayload,
+	meta: {
+		key: 'assistant.answer.delivered',
+		version: '1.0.0',
+		description:
+			'Assistant answer delivered (must include KB snapshot citations).',
+		stability: 'experimental',
+		owners: ['@examples'],
+		tags: ['assistant', 'policy', 'delivered'],
+	},
+	payload: AssistantAnswerDeliveredPayload,
 });

package/src/example.ts

@@ -1,34 +1,34 @@
 import { defineExample } from '@contractspec/lib.contracts-spec';
 
 const example = defineExample({
-  meta: {
-    key: 'locale-jurisdiction-gate',
-    version: '1.0.0',
-    title: 'Locale / Jurisdiction Gate',
-    description:
-      'Fail-closed gating for assistant calls: locale + jurisdiction + kbSnapshotId + allowedScope must be explicit, answers must cite a snapshot.',
-    kind: 'knowledge',
-    visibility: 'public',
-    stability: 'experimental',
-    owners: ['@platform.core'],
-    tags: ['policy', 'locale', 'jurisdiction', 'assistant', 'gating'],
-  },
-  docs: {
-    rootDocId: 'docs.examples.locale-jurisdiction-gate',
-  },
-  entrypoints: {
-    packageName: '@contractspec/example.locale-jurisdiction-gate',
-    feature: './feature',
-    contracts: './contracts',
-    handlers: './handlers',
-    docs: './docs',
-  },
-  surfaces: {
-    templates: true,
-    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
-    studio: { enabled: true, installable: true },
-    mcp: { enabled: true },
-  },
+	meta: {
+		key: 'locale-jurisdiction-gate',
+		version: '1.0.0',
+		title: 'Locale / Jurisdiction Gate',
+		description:
+			'Fail-closed gating for assistant calls: locale + jurisdiction + kbSnapshotId + allowedScope must be explicit, answers must cite a snapshot.',
+		kind: 'knowledge',
+		visibility: 'public',
+		stability: 'experimental',
+		owners: ['@platform.core'],
+		tags: ['policy', 'locale', 'jurisdiction', 'assistant', 'gating'],
+	},
+	docs: {
+		rootDocId: 'docs.examples.locale-jurisdiction-gate',
+	},
+	entrypoints: {
+		packageName: '@contractspec/example.locale-jurisdiction-gate',
+		feature: './feature',
+		contracts: './contracts',
+		handlers: './handlers',
+		docs: './docs',
+	},
+	surfaces: {
+		templates: true,
+		sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+		studio: { enabled: true, installable: true },
+		mcp: { enabled: true },
+	},
 });
 
 export default example;

package/src/forms/assistant-context.form.ts

@@ -0,0 +1,112 @@
+import { defineFormSpec } from '@contractspec/lib.contracts-spec/forms';
+import {
+	OwnersEnum,
+	StabilityEnum,
+	TagsEnum,
+} from '@contractspec/lib.contracts-spec/ownership';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import { AllowedScopeEnum } from '../entities/models';
+
+const AssistantContextFormModel = defineSchemaModel({
+	name: 'AssistantContextFormModel',
+	description:
+		'Form values required before a policy-gated assistant request can be executed.',
+	fields: {
+		locale: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		kbSnapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+		allowedScope: { type: AllowedScopeEnum, isOptional: false },
+		question: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+	},
+});
+
+export const AssistantContextForm = defineFormSpec({
+	meta: {
+		key: 'locale-jurisdiction-gate.form.assistant-context',
+		version: '1.0.0',
+		title: 'Assistant Context Gate',
+		description:
+			'Collects the explicit locale, jurisdiction, scope, and knowledge snapshot required by the assistant gate.',
+		domain: 'assistant',
+		owners: [OwnersEnum.PlatformFinance],
+		tags: [TagsEnum.I18n, 'assistant', 'form', 'policy'],
+		stability: StabilityEnum.Experimental,
+	},
+	model: AssistantContextFormModel,
+	fields: [
+		{
+			kind: 'select',
+			name: 'locale',
+			labelI18n: 'assistantGate.locale.label',
+			descriptionI18n: 'assistantGate.locale.description',
+			options: {
+				kind: 'static',
+				options: [
+					{ labelI18n: 'assistantGate.locale.enUs', value: 'en-US' },
+					{ labelI18n: 'assistantGate.locale.enGb', value: 'en-GB' },
+					{ labelI18n: 'assistantGate.locale.frFr', value: 'fr-FR' },
+				],
+			},
+			required: true,
+		},
+		{
+			kind: 'text',
+			name: 'jurisdiction',
+			labelI18n: 'assistantGate.jurisdiction.label',
+			placeholderI18n: 'assistantGate.jurisdiction.placeholder',
+			required: true,
+		},
+		{
+			kind: 'text',
+			name: 'kbSnapshotId',
+			labelI18n: 'assistantGate.kbSnapshotId.label',
+			placeholderI18n: 'assistantGate.kbSnapshotId.placeholder',
+			required: true,
+		},
+		{
+			kind: 'radio',
+			name: 'allowedScope',
+			labelI18n: 'assistantGate.allowedScope.label',
+			options: {
+				kind: 'static',
+				options: [
+					{
+						labelI18n: 'assistantGate.allowedScope.educationOnly',
+						value: 'education_only',
+					},
+					{
+						labelI18n: 'assistantGate.allowedScope.genericInfo',
+						value: 'generic_info',
+					},
+					{
+						labelI18n: 'assistantGate.allowedScope.escalationRequired',
+						value: 'escalation_required',
+					},
+				],
+			},
+			required: true,
+		},
+		{
+			kind: 'textarea',
+			name: 'question',
+			labelI18n: 'assistantGate.question.label',
+			placeholderI18n: 'assistantGate.question.placeholder',
+			required: true,
+		},
+	],
+	actions: [
+		{
+			key: 'submit',
+			labelI18n: 'assistantGate.submit.label',
+			op: { name: 'assistant.answer', version: '1.0.0' },
+		},
+	],
+	policy: {
+		flags: [],
+		pii: ['kbSnapshotId', 'question'],
+	},
+	renderHints: {
+		ui: 'custom',
+		form: 'react-hook-form',
+	},
+});

package/src/forms/index.ts

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

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

@@ -3,52 +3,52 @@ import { describe, expect, it } from 'bun:test';
 import { createDemoAssistantHandlers } from './demo.handlers';
 
 describe('@contractspec/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 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 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');
-  });
+	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');
+	});
 });