@contractspec/example.locale-jurisdiction-gate 1.44.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@contractspec/example.locale-jurisdiction-gate",
+  "version": "1.44.0",
+  "description": "Example: enforce locale + jurisdiction + kbSnapshotId + allowed scope for assistant calls (fail-closed).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "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": "1.44.0",
+    "@contractspec/lib.schema": "1.44.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "1.44.0",
+    "@contractspec/tool.typescript": "1.44.0",
+    "tsdown": "^0.18.3",
+    "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,
+    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,
+    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,
+    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,27 @@
+const example = {
+  id: 'locale-jurisdiction-gate',
+  title: 'Locale / Jurisdiction Gate',
+  summary:
+    'Fail-closed gating for assistant calls: locale + jurisdiction + kbSnapshotId + allowedScope must be explicit, answers must cite a snapshot.',
+  tags: ['policy', 'locale', 'jurisdiction', 'assistant', 'gating'],
+  kind: 'knowledge',
+  visibility: 'public',
+  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 },
+  },
+} as const;
+
+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');
+  });
+});

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 type { FeatureModuleSpec } from '@contractspec/lib.contracts';
+
+export const LocaleJurisdictionGateFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'locale-jurisdiction-gate',
+    version: 1,
+    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 },
+    { key: 'assistant.explainConcept', version: 1 },
+  ],
+  events: [
+    { key: 'assistant.answer.requested', version: 1 },
+    { key: 'assistant.answer.blocked', version: 1 },
+    { key: 'assistant.answer.delivered', version: 1 },
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    requires: [{ key: 'knowledge', version: 1 }],
+  },
+};