@lssm/example.locale-jurisdiction-gate 0.0.0-canary-20251213172311

package/.turbo/turbo-build.log

@@ -0,0 +1,26 @@
+$ bun build:bundle && bun build:types
+$ tsdown
+ℹ tsdown v0.17.0 powered by rolldown v1.0.0-beta.53
+ℹ config file: /home/runner/work/contractspec/contractspec/packages/examples/locale-jurisdiction-gate/tsdown.config.js 
+ℹ entry: src/events.ts, src/example.ts, src/feature.ts, src/index.ts, src/docs/index.ts, src/docs/locale-jurisdiction-gate.docblock.ts, src/entities/index.ts, src/entities/models.ts, src/contracts/assistant.ts, src/contracts/index.ts, src/handlers/demo.handlers.ts, src/handlers/index.ts, src/policy/guard.ts, src/policy/index.ts, src/policy/types.ts
+ℹ target: esnext
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ dist/entities/models.js                         2.50 kB │ gzip: 0.74 kB
+ℹ dist/contracts/assistant.js                     2.34 kB │ gzip: 0.93 kB
+ℹ dist/events.js                                  1.69 kB │ gzip: 0.48 kB
+ℹ dist/handlers/demo.handlers.js                  1.55 kB │ gzip: 0.69 kB
+ℹ dist/docs/locale-jurisdiction-gate.docblock.js  1.40 kB │ gzip: 0.67 kB
+ℹ dist/index.js                                   1.31 kB │ gzip: 0.46 kB
+ℹ dist/policy/guard.js                            1.18 kB │ gzip: 0.61 kB
+ℹ dist/feature.js                                 0.72 kB │ gzip: 0.36 kB
+ℹ dist/example.js                                 0.67 kB │ gzip: 0.40 kB
+ℹ dist/entities/index.js                          0.41 kB │ gzip: 0.19 kB
+ℹ dist/policy/index.js                            0.17 kB │ gzip: 0.12 kB
+ℹ dist/contracts/index.js                         0.17 kB │ gzip: 0.11 kB
+ℹ dist/handlers/index.js                          0.11 kB │ gzip: 0.09 kB
+ℹ dist/docs/index.js                              0.05 kB │ gzip: 0.07 kB
+ℹ dist/policy/types.js                            0.00 kB │ gzip: 0.02 kB
+ℹ 15 files, total: 14.27 kB
+✔ Build complete in 64ms
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @lssm/example.locale-jurisdiction-gate
+
+## 0.0.0-canary-20251213172311
+
+### Patch Changes
+
+- Updated dependencies [3086383]
+  - @lssm/lib.contracts@0.0.0-canary-20251213172311
+  - @lssm/lib.schema@0.0.0-canary-20251213172311

package/README.md

@@ -0,0 +1,31 @@
+# `@lssm/example.locale-jurisdiction-gate`
+
+Spec-first example showing how to **fail-closed** on every assistant call unless:
+
+- `locale` is provided and supported
+- `jurisdiction` is provided
+- `kbSnapshotId` is provided
+- `allowedScope` is provided and respected
+- answers include **at least one citation** (or the call is refused)
+
+## What this example demonstrates
+
+- **Locale + jurisdiction as explicit inputs** (no guessing)
+- **Structured Answer IR** with citations, disclaimers, and risk flags
+- **Scope enforcement**: blocks scope-violating content under restricted scopes
+- **Traceability**: emits events for requested / blocked / delivered
+
+## Key exports
+
+- `contracts`: `assistant.answer`, `assistant.explainConcept`
+- `entities/models`: `LLMCallEnvelope`, `AssistantAnswerIR`, `RegulatoryContext`
+- `policy/guard`: pure gate functions used by handlers and tests
+- `handlers/demo.handlers`: deterministic demo handlers (no LLM)
+
+## Running tests
+
+```bash
+bun test
+```
+
+

package/dist/contracts/assistant.js

@@ -0,0 +1 @@
+import{AssistantAnswerIRModel as e,LLMCallEnvelopeModel as t}from"../entities/models.js";import{defineCommand as n}from"@lssm/lib.contracts";import{ScalarTypeEnum as r,defineSchemaModel as i}from"@lssm/lib.schema";const a=i({name:`AssistantQuestionInput`,description:`Input for assistant calls with mandatory envelope.`,fields:{envelope:{type:t,isOptional:!1},question:{type:r.String_unsecure(),isOptional:!1}}}),o=i({name:`AssistantConceptInput`,description:`Input for explaining a concept with mandatory envelope.`,fields:{envelope:{type:t,isOptional:!1},conceptKey:{type:r.String_unsecure(),isOptional:!1}}}),s=n({meta:{name:`assistant.answer`,version:1,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:a,output:e,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`}}),c=n({meta:{name:`assistant.explainConcept`,version:1,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:o,output:e,errors:s.io.errors},policy:{auth:`user`}});export{s as AssistantAnswerContract,c as AssistantExplainConceptContract};

package/dist/contracts/index.js

@@ -0,0 +1 @@
+import{AssistantAnswerContract as e,AssistantExplainConceptContract as t}from"./assistant.js";export{e as AssistantAnswerContract,t as AssistantExplainConceptContract};

package/dist/docs/index.js

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

package/dist/docs/locale-jurisdiction-gate.docblock.js

@@ -0,0 +1,19 @@
+import{registerDocBlocks as e}from"@lssm/lib.contracts/docs";e([{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`}]);

package/dist/entities/index.js

@@ -0,0 +1 @@
+import{AllowedScopeEnum as e,AssistantAnswerIRModel as t,AssistantAnswerSectionModel as n,AssistantCitationModel as r,LLMCallEnvelopeModel as i,RegulatoryContextModel as a,UserProfileModel as o}from"./models.js";export{e as AllowedScopeEnum,t as AssistantAnswerIRModel,n as AssistantAnswerSectionModel,r as AssistantCitationModel,i as LLMCallEnvelopeModel,a as RegulatoryContextModel,o as UserProfileModel};

package/dist/entities/models.js

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

package/dist/events.js

@@ -0,0 +1 @@
+import{defineEvent as e,defineSchemaModel as t}from"@lssm/lib.contracts";import{ScalarTypeEnum as n}from"@lssm/lib.schema";const r=e({name:`assistant.answer.requested`,version:1,description:`Assistant answer requested (policy gate will run).`,payload:t({name:`AssistantAnswerRequestedPayload`,description:`Emitted when an assistant answer is requested (pre-gate).`,fields:{traceId:{type:n.String_unsecure(),isOptional:!1},locale:{type:n.String_unsecure(),isOptional:!1},jurisdiction:{type:n.String_unsecure(),isOptional:!1},kbSnapshotId:{type:n.String_unsecure(),isOptional:!1},allowedScope:{type:n.String_unsecure(),isOptional:!1}}})}),i=e({name:`assistant.answer.blocked`,version:1,description:`Assistant answer blocked (fail-closed).`,payload:t({name:`AssistantAnswerBlockedPayload`,description:`Emitted when a request is blocked by the gate.`,fields:{traceId:{type:n.String_unsecure(),isOptional:!1},reasonCode:{type:n.String_unsecure(),isOptional:!1},reason:{type:n.String_unsecure(),isOptional:!1}}})}),a=e({name:`assistant.answer.delivered`,version:1,description:`Assistant answer delivered (must include KB snapshot citations).`,payload:t({name:`AssistantAnswerDeliveredPayload`,description:`Emitted when a structured, cited answer is delivered.`,fields:{traceId:{type:n.String_unsecure(),isOptional:!1},locale:{type:n.String_unsecure(),isOptional:!1},jurisdiction:{type:n.String_unsecure(),isOptional:!1},kbSnapshotId:{type:n.String_unsecure(),isOptional:!1},allowedScope:{type:n.String_unsecure(),isOptional:!1},citationsCount:{type:n.Int_unsecure(),isOptional:!1}}})});export{i as AssistantAnswerBlockedEvent,a as AssistantAnswerDeliveredEvent,r as AssistantAnswerRequestedEvent};

package/dist/example.js

@@ -0,0 +1 @@
+var e={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:`@lssm/example.locale-jurisdiction-gate`,feature:`./feature`,contracts:`./contracts`,handlers:`./handlers`,docs:`./docs`},surfaces:{templates:!0,sandbox:{enabled:!0,modes:[`markdown`,`specs`]},studio:{enabled:!0,installable:!0},mcp:{enabled:!0}}};export{e as default};

package/dist/feature.js

@@ -0,0 +1 @@
+const e={meta:{key:`locale-jurisdiction-gate`,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:[{name:`assistant.answer`,version:1},{name:`assistant.explainConcept`,version:1}],events:[{name:`assistant.answer.requested`,version:1},{name:`assistant.answer.blocked`,version:1},{name:`assistant.answer.delivered`,version:1}],presentations:[],opToPresentation:[],presentationsTargets:[],capabilities:{requires:[{key:`knowledge`,version:1}]}};export{e as LocaleJurisdictionGateFeature};

package/dist/handlers/demo.handlers.js

@@ -0,0 +1 @@
+import{enforceAllowedScope as e,enforceCitations as t,validateEnvelope as n}from"../policy/guard.js";function r(){async function r(r){let i=n(r.envelope);if(!i.ok)return{locale:r.envelope.locale??`en-US`,jurisdiction:r.envelope.regulatoryContext?.jurisdiction??`UNKNOWN`,allowedScope:r.envelope.allowedScope??`education_only`,sections:[{heading:`Request blocked`,body:i.error.message}],citations:[],disclaimers:[`This system refuses to answer without a valid envelope.`],riskFlags:[i.error.code],refused:!0,refusalReason:i.error.code};let a={locale:i.value.locale,jurisdiction:i.value.regulatoryContext.jurisdiction,allowedScope:i.value.allowedScope,sections:[{heading:`Answer (demo)`,body:`You asked: "${r.question}". This demo answer is derived from the KB snapshot only.`}],citations:[{kbSnapshotId:i.value.kbSnapshotId,sourceType:`ruleVersion`,sourceId:`rv_demo`,title:`Demo rule version`,excerpt:`Demo excerpt`}],disclaimers:[`Educational demo only.`],riskFlags:[]},o=e(i.value.allowedScope,a);if(!o.ok)return{...a,sections:[{heading:`Escalation required`,body:o.error.message}],citations:a.citations,refused:!0,refusalReason:o.error.code,riskFlags:[...a.riskFlags??[],o.error.code]};let s=t(a);return s.ok?a:{...a,sections:[{heading:`Request blocked`,body:s.error.message}],citations:[],refused:!0,refusalReason:s.error.code,riskFlags:[...a.riskFlags??[],s.error.code]}}async function i(e){return await r({envelope:e.envelope,question:`Explain concept: ${e.conceptKey}`})}return{answer:r,explainConcept:i}}export{r as createDemoAssistantHandlers};

package/dist/handlers/index.js

@@ -0,0 +1 @@
+import{createDemoAssistantHandlers as e}from"./demo.handlers.js";export{e as createDemoAssistantHandlers};

package/dist/index.js

@@ -0,0 +1 @@
+import{AssistantAnswerBlockedEvent as e,AssistantAnswerDeliveredEvent as t,AssistantAnswerRequestedEvent as n}from"./events.js";import r from"./example.js";import{LocaleJurisdictionGateFeature as i}from"./feature.js";import{AllowedScopeEnum as a,AssistantAnswerIRModel as o,AssistantAnswerSectionModel as s,AssistantCitationModel as c,LLMCallEnvelopeModel as l,RegulatoryContextModel as u,UserProfileModel as d}from"./entities/models.js";import"./entities/index.js";import{AssistantAnswerContract as f,AssistantExplainConceptContract as p}from"./contracts/assistant.js";import"./contracts/index.js";import{enforceAllowedScope as m,enforceCitations as h,validateEnvelope as g}from"./policy/guard.js";import{createDemoAssistantHandlers as _}from"./handlers/demo.handlers.js";import"./docs/index.js";export{a as AllowedScopeEnum,e as AssistantAnswerBlockedEvent,f as AssistantAnswerContract,t as AssistantAnswerDeliveredEvent,o as AssistantAnswerIRModel,n as AssistantAnswerRequestedEvent,s as AssistantAnswerSectionModel,c as AssistantCitationModel,p as AssistantExplainConceptContract,l as LLMCallEnvelopeModel,i as LocaleJurisdictionGateFeature,u as RegulatoryContextModel,d as UserProfileModel,_ as createDemoAssistantHandlers,m as enforceAllowedScope,h as enforceCitations,r as example,g as validateEnvelope};

package/dist/policy/guard.js

@@ -0,0 +1,2 @@
+const e=new Set([`en-US`,`en-GB`,`fr-FR`]);function t(e,t){return{code:e,message:t}}function n(n){return!n.locale||!e.has(n.locale)?{ok:!1,error:t(`LOCALE_REQUIRED`,`locale is required and must be supported`)}:n.regulatoryContext?.jurisdiction?n.kbSnapshotId?n.allowedScope?{ok:!0,value:n}:{ok:!1,error:t(`SCOPE_VIOLATION`,`allowedScope is required`)}:{ok:!1,error:t(`KB_SNAPSHOT_REQUIRED`,`kbSnapshotId is required`)}:{ok:!1,error:t(`JURISDICTION_REQUIRED`,`jurisdiction is required`)}}function r(e){let n=e.citations??[];return!Array.isArray(n)||n.length===0?{ok:!1,error:t(`CITATIONS_REQUIRED`,`answers must include at least one citation`)}:{ok:!0,value:e}}const i=[/\b(buy|sell)\b/i,/\b(should\s+buy|should\s+sell)\b/i,/\b(guarantee(d)?|promise(d)?)\b/i];function a(e,n){if(!e)return{ok:!1,error:t(`SCOPE_VIOLATION`,`allowedScope is required`)};if(e!==`education_only`)return{ok:!0,value:n};let r=(n.sections??[]).map(e=>e.body).join(`
+`);return i.some(e=>e.test(r))?{ok:!1,error:t(`SCOPE_VIOLATION`,`answer violates education_only scope (contains actionable or promotional language)`)}:{ok:!0,value:n}}export{a as enforceAllowedScope,r as enforceCitations,n as validateEnvelope};

package/dist/policy/index.js

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

package/example.ts

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

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@lssm/example.locale-jurisdiction-gate",
+  "version": "0.0.0-canary-20251213172311",
+  "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": {
+    ".": "./src/index.ts",
+    "./contracts": "./src/contracts/index.ts",
+    "./contracts/assistant": "./src/contracts/assistant.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/locale-jurisdiction-gate.docblock": "./src/docs/locale-jurisdiction-gate.docblock.ts",
+    "./entities": "./src/entities/index.ts",
+    "./entities/models": "./src/entities/models.ts",
+    "./events": "./src/events.ts",
+    "./example": "./src/example.ts",
+    "./feature": "./src/feature.ts",
+    "./handlers": "./src/handlers/index.ts",
+    "./handlers/demo.handlers": "./src/handlers/demo.handlers.ts",
+    "./policy": "./src/policy/index.ts",
+    "./policy/guard": "./src/policy/guard.ts",
+    "./policy/types": "./src/policy/types.ts",
+    "./*": "./*"
+  },
+  "scripts": {
+    "build": "bun build:bundle && bun build:types",
+    "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": {
+    "@lssm/lib.contracts": "workspace:*",
+    "@lssm/lib.schema": "workspace:*",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.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",
+      "./feature": "./dist/feature.js",
+      "./handlers": "./dist/handlers/index.js",
+      "./handlers/demo.handlers": "./dist/handlers/demo.handlers.js",
+      "./policy": "./dist/policy/index.js",
+      "./policy/guard": "./dist/policy/guard.js",
+      "./policy/types": "./dist/policy/types.js",
+      "./*": "./*"
+    }
+  }
+}

package/src/contracts/assistant.ts

@@ -0,0 +1,96 @@
+import { defineCommand } from '@lssm/lib.contracts';
+import { ScalarTypeEnum, defineSchemaModel } from '@lssm/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: {
+    name: 'assistant.answer',
+    version: 1,
+    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: {
+    name: 'assistant.explainConcept',
+    version: 1,
+    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/contracts/index.ts

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

package/src/docs/index.ts

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

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

@@ -0,0 +1,48 @@
+import type { DocBlock } from '@lssm/lib.contracts/docs';
+import { registerDocBlocks } from '@lssm/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,3 @@
+export * from './models';
+
+

package/src/entities/models.ts

@@ -0,0 +1,101 @@
+import { ScalarTypeEnum, defineEnum, defineSchemaModel } from '@lssm/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,61 @@
+import { defineEvent, defineSchemaModel } from '@lssm/lib.contracts';
+import { ScalarTypeEnum } from '@lssm/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({
+  name: 'assistant.answer.requested',
+  version: 1,
+  description: 'Assistant answer requested (policy gate will run).',
+  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({
+  name: 'assistant.answer.blocked',
+  version: 1,
+  description: 'Assistant answer blocked (fail-closed).',
+  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({
+  name: 'assistant.answer.delivered',
+  version: 1,
+  description:
+    'Assistant answer delivered (must include KB snapshot citations).',
+  payload: AssistantAnswerDeliveredPayload,
+});
+
+

package/src/example.ts

@@ -0,0 +1,29 @@
+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: '@lssm/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/feature.ts

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