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

package/dist/policy/guard.d.ts

@@ -0,0 +1,27 @@
+import { GateResult } from "./types.js";
+
+//#region src/policy/guard.d.ts
+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';
+}
+declare function validateEnvelope(envelope: EnvelopeLike): GateResult<Required<EnvelopeLike>>;
+declare function enforceCitations(answer: AnswerLike): GateResult<AnswerLike>;
+declare function enforceAllowedScope(allowedScope: EnvelopeLike['allowedScope'], answer: AnswerLike): GateResult<AnswerLike>;
+//#endregion
+export { enforceAllowedScope, enforceCitations, validateEnvelope };
+//# sourceMappingURL=guard.d.ts.map

package/dist/policy/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","names":[],"sources":["../../src/policy/guard.ts"],"sourcesContent":[],"mappings":";;;UAEU,YAAA;;EAAA,YAAA,CAAA,EAAY,MAAA;EAOZ,YAAA,CAAU,EAAA,gBAAA,GAAA,cAAA,GAAA,qBAAA;EAcJ,iBAAA,CAAA,EAAgB;IACpB,YAAA,CAAA,EAAA,MAAA;EACW,CAAA;;UAhBb,UAAA,CAgBP;EAAU,SAAA,CAAA,EAAA,OAAA,EAAA;EA4BG,QAAA,CAAA,EAAA;IAAyB,OAAA,EAAA,MAAA;IAAwB,IAAA,EAAA,MAAA;EAAX,CAAA,EAAA;EAAU,OAAA,CAAA,EAAA,OAAA;EAoBhD,aAAA,CAAA,EAAA,MAAmB;EACnB,YAAA,CAAA,EAAA,gBAAA,GAAA,cAAA,GAAA,qBAAA;;AAEF,iBArDE,gBAAA,CAqDF,QAAA,EApDF,YAoDE,CAAA,EAnDX,UAmDW,CAnDA,QAmDA,CAnDS,YAmDT,CAAA,CAAA;AAAX,iBAvBa,gBAAA,CAuBb,MAAA,EAvBsC,UAuBtC,CAAA,EAvBmD,UAuBnD,CAvB8D,UAuB9D,CAAA;AAAU,iBAHG,mBAAA,CAGH,YAAA,EAFG,YAEH,CAAA,cAAA,CAAA,EAAA,MAAA,EADH,UACG,CAAA,EAAV,UAAU,CAAC,UAAD,CAAA"}

package/dist/policy/guard.js

@@ -0,0 +1,73 @@
+//#region src/policy/guard.ts
+const SUPPORTED_LOCALES = new Set([
+	"en-US",
+	"en-GB",
+	"fr-FR"
+]);
+function err(code, message) {
+	return {
+		code,
+		message
+	};
+}
+function validateEnvelope(envelope) {
+	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
+	};
+}
+function enforceCitations(answer) {
+	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 = [
+	/\b(buy|sell)\b/i,
+	/\b(should\s+buy|should\s+sell)\b/i,
+	/\b(guarantee(d)?|promise(d)?)\b/i
+];
+function enforceAllowedScope(allowedScope, answer) {
+	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");
+	if (EDUCATION_ONLY_FORBIDDEN_PATTERNS.some((re) => re.test(bodies))) return {
+		ok: false,
+		error: err("SCOPE_VIOLATION", "answer violates education_only scope (contains actionable or promotional language)")
+	};
+	return {
+		ok: true,
+		value: answer
+	};
+}
+
+//#endregion
+export { enforceAllowedScope, enforceCitations, validateEnvelope };
+//# sourceMappingURL=guard.js.map

package/dist/policy/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","names":[],"sources":["../../src/policy/guard.ts"],"sourcesContent":["import type { GateError, GateResult } from './types';\n\ninterface EnvelopeLike {\n  locale?: string;\n  kbSnapshotId?: string;\n  allowedScope?: 'education_only' | 'generic_info' | 'escalation_required';\n  regulatoryContext?: { jurisdiction?: string };\n}\n\ninterface AnswerLike {\n  citations?: unknown[];\n  sections?: { heading: string; body: string }[];\n  refused?: boolean;\n  refusalReason?: string;\n  allowedScope?: 'education_only' | 'generic_info' | 'escalation_required';\n}\n\nconst SUPPORTED_LOCALES = new Set<string>(['en-US', 'en-GB', 'fr-FR']);\n\nfunction err(code: GateError['code'], message: string): GateError {\n  return { code, message };\n}\n\nexport function validateEnvelope(\n  envelope: EnvelopeLike\n): GateResult<Required<EnvelopeLike>> {\n  if (!envelope.locale || !SUPPORTED_LOCALES.has(envelope.locale)) {\n    return {\n      ok: false,\n      error: err('LOCALE_REQUIRED', 'locale is required and must be supported'),\n    };\n  }\n  if (!envelope.regulatoryContext?.jurisdiction) {\n    return {\n      ok: false,\n      error: err('JURISDICTION_REQUIRED', 'jurisdiction is required'),\n    };\n  }\n  if (!envelope.kbSnapshotId) {\n    return {\n      ok: false,\n      error: err('KB_SNAPSHOT_REQUIRED', 'kbSnapshotId is required'),\n    };\n  }\n  if (!envelope.allowedScope) {\n    return {\n      ok: false,\n      error: err('SCOPE_VIOLATION', 'allowedScope is required'),\n    };\n  }\n  return { ok: true, value: envelope as Required<EnvelopeLike> };\n}\n\nexport function enforceCitations(answer: AnswerLike): GateResult<AnswerLike> {\n  const citations = answer.citations ?? [];\n  if (!Array.isArray(citations) || citations.length === 0) {\n    return {\n      ok: false,\n      error: err(\n        'CITATIONS_REQUIRED',\n        'answers must include at least one citation'\n      ),\n    };\n  }\n  return { ok: true, value: answer };\n}\n\nconst EDUCATION_ONLY_FORBIDDEN_PATTERNS: RegExp[] = [\n  /\\b(buy|sell)\\b/i,\n  /\\b(should\\s+buy|should\\s+sell)\\b/i,\n  /\\b(guarantee(d)?|promise(d)?)\\b/i,\n];\n\nexport function enforceAllowedScope(\n  allowedScope: EnvelopeLike['allowedScope'],\n  answer: AnswerLike\n): GateResult<AnswerLike> {\n  if (!allowedScope) {\n    return {\n      ok: false,\n      error: err('SCOPE_VIOLATION', 'allowedScope is required'),\n    };\n  }\n  if (allowedScope !== 'education_only') {\n    return { ok: true, value: answer };\n  }\n\n  const bodies = (answer.sections ?? []).map((s) => s.body).join('\\n');\n  const violations = EDUCATION_ONLY_FORBIDDEN_PATTERNS.some((re) =>\n    re.test(bodies)\n  );\n  if (violations) {\n    return {\n      ok: false,\n      error: err(\n        'SCOPE_VIOLATION',\n        'answer violates education_only scope (contains actionable or promotional language)'\n      ),\n    };\n  }\n  return { ok: true, value: answer };\n}\n"],"mappings":";AAiBA,MAAM,oBAAoB,IAAI,IAAY;CAAC;CAAS;CAAS;CAAQ,CAAC;AAEtE,SAAS,IAAI,MAAyB,SAA4B;AAChE,QAAO;EAAE;EAAM;EAAS;;AAG1B,SAAgB,iBACd,UACoC;AACpC,KAAI,CAAC,SAAS,UAAU,CAAC,kBAAkB,IAAI,SAAS,OAAO,CAC7D,QAAO;EACL,IAAI;EACJ,OAAO,IAAI,mBAAmB,2CAA2C;EAC1E;AAEH,KAAI,CAAC,SAAS,mBAAmB,aAC/B,QAAO;EACL,IAAI;EACJ,OAAO,IAAI,yBAAyB,2BAA2B;EAChE;AAEH,KAAI,CAAC,SAAS,aACZ,QAAO;EACL,IAAI;EACJ,OAAO,IAAI,wBAAwB,2BAA2B;EAC/D;AAEH,KAAI,CAAC,SAAS,aACZ,QAAO;EACL,IAAI;EACJ,OAAO,IAAI,mBAAmB,2BAA2B;EAC1D;AAEH,QAAO;EAAE,IAAI;EAAM,OAAO;EAAoC;;AAGhE,SAAgB,iBAAiB,QAA4C;CAC3E,MAAM,YAAY,OAAO,aAAa,EAAE;AACxC,KAAI,CAAC,MAAM,QAAQ,UAAU,IAAI,UAAU,WAAW,EACpD,QAAO;EACL,IAAI;EACJ,OAAO,IACL,sBACA,6CACD;EACF;AAEH,QAAO;EAAE,IAAI;EAAM,OAAO;EAAQ;;AAGpC,MAAM,oCAA8C;CAClD;CACA;CACA;CACD;AAED,SAAgB,oBACd,cACA,QACwB;AACxB,KAAI,CAAC,aACH,QAAO;EACL,IAAI;EACJ,OAAO,IAAI,mBAAmB,2BAA2B;EAC1D;AAEH,KAAI,iBAAiB,iBACnB,QAAO;EAAE,IAAI;EAAM,OAAO;EAAQ;CAGpC,MAAM,UAAU,OAAO,YAAY,EAAE,EAAE,KAAK,MAAM,EAAE,KAAK,CAAC,KAAK,KAAK;AAIpE,KAHmB,kCAAkC,MAAM,OACzD,GAAG,KAAK,OAAO,CAChB,CAEC,QAAO;EACL,IAAI;EACJ,OAAO,IACL,mBACA,qFACD;EACF;AAEH,QAAO;EAAE,IAAI;EAAM,OAAO;EAAQ"}

package/dist/policy/index.d.ts

@@ -0,0 +1,3 @@
+import { AllowedScope, GateError, GateResult } from "./types.js";
+import { enforceAllowedScope, enforceCitations, validateEnvelope } from "./guard.js";
+export { AllowedScope, GateError, GateResult, enforceAllowedScope, enforceCitations, validateEnvelope };

package/dist/policy/index.js

@@ -0,0 +1,3 @@
+import { enforceAllowedScope, enforceCitations, validateEnvelope } from "./guard.js";
+
+export { enforceAllowedScope, enforceCitations, validateEnvelope };

package/dist/policy/types.d.ts

@@ -0,0 +1,16 @@
+//#region src/policy/types.d.ts
+type AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';
+interface GateError {
+  code: 'LOCALE_REQUIRED' | 'JURISDICTION_REQUIRED' | 'KB_SNAPSHOT_REQUIRED' | 'CITATIONS_REQUIRED' | 'SCOPE_VIOLATION';
+  message: string;
+}
+type GateResult<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: GateError;
+};
+//#endregion
+export { AllowedScope, GateError, GateResult };
+//# sourceMappingURL=types.d.ts.map

package/dist/policy/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/policy/types.ts"],"sourcesContent":[],"mappings":";KAAY,YAAA;AAAA,UAKK,SAAA,CALO;EAKP,IAAA,EAAA,iBAAS,GAAA,uBAAA,GAAA,sBAAA,GAAA,oBAAA,GAAA,iBAAA;EAUd,OAAA,EAAA,MAAU;;KAAV;;SACW;;;SACC"}

package/example.ts

@@ -0,0 +1 @@
+export { default } from './src/example';

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@contractspec/example.locale-jurisdiction-gate",
+  "version": "0.0.0-canary-20260113162409",
+  "description": "Example: enforce locale + jurisdiction + kbSnapshotId + allowed scope for assistant calls (fail-closed).",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/locale-jurisdiction-gate.docblock": "./dist/docs/locale-jurisdiction-gate.docblock.js",
+    "./entities": "./dist/entities/index.js",
+    "./entities/models": "./dist/entities/models.js",
+    "./events": "./dist/events.js",
+    "./example": "./dist/example.js",
+    "./handlers": "./dist/handlers/index.js",
+    "./handlers/demo.handlers": "./dist/handlers/demo.handlers.js",
+    "./locale-jurisdiction-gate.feature": "./dist/locale-jurisdiction-gate.feature.js",
+    "./operations": "./dist/operations/index.js",
+    "./operations/assistant": "./dist/operations/assistant.js",
+    "./policy": "./dist/policy/index.js",
+    "./policy/guard": "./dist/policy/guard.js",
+    "./policy/types": "./dist/policy/types.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113162409",
+    "@contractspec/lib.schema": "0.0.0-canary-20260113162409"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113162409",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113162409",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./contracts": "./dist/contracts/index.js",
+      "./contracts/assistant": "./dist/contracts/assistant.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/locale-jurisdiction-gate.docblock": "./dist/docs/locale-jurisdiction-gate.docblock.js",
+      "./entities": "./dist/entities/index.js",
+      "./entities/models": "./dist/entities/models.js",
+      "./events": "./dist/events.js",
+      "./example": "./dist/example.js",
+      "./handlers": "./dist/handlers/index.js",
+      "./handlers/demo.handlers": "./dist/handlers/demo.handlers.js",
+      "./locale-jurisdiction-gate.feature": "./dist/locale-jurisdiction-gate.feature.js",
+      "./policy": "./dist/policy/index.js",
+      "./policy/guard": "./dist/policy/guard.js",
+      "./policy/types": "./dist/policy/types.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/locale-jurisdiction-gate"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './locale-jurisdiction-gate.docblock';

package/src/docs/locale-jurisdiction-gate.docblock.ts

@@ -0,0 +1,46 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const docBlocks: DocBlock[] = [
+  {
+    id: 'docs.examples.locale-jurisdiction-gate.goal',
+    title: 'Locale/Jurisdiction Gate — Goal',
+    summary:
+      'Fail-closed gate that forces locale + jurisdiction + kbSnapshotId + allowedScope for assistant calls.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/examples/locale-jurisdiction-gate/goal',
+    tags: ['assistant', 'policy', 'locale', 'jurisdiction', 'knowledge'],
+    body: `## Why it matters
+- Forces all assistant behavior to be bound to explicit inputs (no guessing).
+- Requires KB snapshot citations to make answers traceable and regenerable.
+
+## Guardrails
+- Missing locale/jurisdiction/snapshot/scope => refuse (structured).
+- Missing citations => refuse.
+- Scope violations under education_only => refuse/escalate.`,
+  },
+  {
+    id: 'docs.examples.locale-jurisdiction-gate.reference',
+    title: 'Locale/Jurisdiction Gate — Reference',
+    summary: 'Contracts, models, and events exposed by the gate example.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/locale-jurisdiction-gate',
+    tags: ['assistant', 'policy', 'reference'],
+    body: `## Contracts
+- assistant.answer (v1)
+- assistant.explainConcept (v1)
+
+## Models
+- LLMCallEnvelope (locale, regulatoryContext, kbSnapshotId, allowedScope, traceId)
+- AssistantAnswerIR (sections, citations, disclaimers, riskFlags)
+
+## Events
+- assistant.answer.requested
+- assistant.answer.blocked
+- assistant.answer.delivered`,
+  },
+];
+
+registerDocBlocks(docBlocks);

package/src/entities/index.ts

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

package/src/entities/models.ts

@@ -0,0 +1,110 @@
+import {
+  ScalarTypeEnum,
+  defineEnum,
+  defineSchemaModel,
+} from '@contractspec/lib.schema';
+
+export const AllowedScopeEnum = defineEnum('AllowedScope', [
+  '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 },
+  },
+});
+
+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 },
+  },
+});
+
+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 },
+  },
+});
+
+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 },
+  },
+});
+
+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 },
+  },
+});
+
+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 },
+  },
+});

package/src/events.ts

@@ -0,0 +1,74 @@
+import { defineEvent, defineSchemaModel } from '@contractspec/lib.contracts';
+import { 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 },
+  },
+});
+
+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,
+});
+
+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 },
+  },
+});
+
+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,
+});
+
+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 },
+  },
+});
+
+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,
+});

package/src/example.ts

@@ -0,0 +1,34 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+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 },
+  },
+});
+
+export default example;

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

@@ -0,0 +1,54 @@
+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 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');
+  });
+});