@lssm/example.policy-safe-knowledge-assistant 0.0.0-canary-20251213172311

package/.turbo/turbo-build.log

@@ -0,0 +1,19 @@
+$ 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/policy-safe-knowledge-assistant/tsdown.config.js 
+ℹ entry: src/example.ts, src/feature.ts, src/index.ts, src/docs/index.ts, src/docs/policy-safe-knowledge-assistant.docblock.ts, src/orchestrator/buildAnswer.ts, src/seed/fixtures.ts, src/seed/index.ts
+ℹ target: esnext
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ dist/orchestrator/buildAnswer.js                       1.65 kB │ gzip: 0.71 kB
+ℹ dist/docs/policy-safe-knowledge-assistant.docblock.js  1.62 kB │ gzip: 0.83 kB
+ℹ dist/feature.js                                        1.57 kB │ gzip: 0.57 kB
+ℹ dist/example.js                                        0.72 kB │ gzip: 0.41 kB
+ℹ dist/seed/fixtures.js                                  0.56 kB │ gzip: 0.31 kB
+ℹ dist/index.js                                          0.35 kB │ gzip: 0.20 kB
+ℹ dist/seed/index.js                                     0.07 kB │ gzip: 0.08 kB
+ℹ dist/docs/index.js                                     0.05 kB │ gzip: 0.07 kB
+ℹ 8 files, total: 6.60 kB
+✔ Build complete in 57ms
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @lssm/example.policy-safe-knowledge-assistant
+
+## 0.0.0-canary-20251213172311
+
+### Patch Changes
+
+- Updated dependencies [3086383]
+  - @lssm/lib.contracts@0.0.0-canary-20251213172311
+  - @lssm/lib.jobs@0.0.0-canary-20251213172311
+  - @lssm/example.kb-update-pipeline@0.0.0-canary-20251213172311
+  - @lssm/example.locale-jurisdiction-gate@0.0.0-canary-20251213172311
+  - @lssm/example.versioned-knowledge-base@0.0.0-canary-20251213172311
+  - @lssm/lib.feature-flags@0.0.0-canary-20251213172311
+  - @lssm/lib.files@0.0.0-canary-20251213172311
+  - @lssm/lib.identity-rbac@0.0.0-canary-20251213172311
+  - @lssm/lib.metering@0.0.0-canary-20251213172311
+  - @lssm/module.audit-trail@0.0.0-canary-20251213172311
+  - @lssm/module.learning-journey@0.0.0-canary-20251213172311
+  - @lssm/module.notifications@0.0.0-canary-20251213172311
+  - @lssm/example.learning-patterns@0.0.0-canary-20251213172311

package/IMPLEMENTATION_SKETCH.md

@@ -0,0 +1,32 @@
+## Implementation sketch — Policy-safe Knowledge Assistant (example)
+
+This example package is **spec-first** and demonstrates how to compose:
+
+- `@lssm/example.locale-jurisdiction-gate`
+- `@lssm/example.versioned-knowledge-base`
+- `@lssm/example.kb-update-pipeline`
+- `@lssm/example.learning-patterns`
+
+The runnable **sandbox UI/runtime** lives in `@lssm/bundle.contractspec-studio` (wired later).
+
+### Package boundaries
+
+- **Gate**: validates `locale`, `jurisdiction`, `kbSnapshotId`, `allowedScope`. Refuses if citations are missing or scope is violated.
+- **Versioned KB**: stores immutable sources and versioned rules; publishes snapshots containing only approved rule versions.
+- **Update Pipeline (HITL)**: detects changes, creates review tasks, gates approvals by risk level; publishing remains blocked until all proposed rule versions are approved.
+- **Learning patterns**: drills/coach/quests as event-driven Learning Journey tracks.
+
+### Key invariants (fail-closed)
+
+- No assistant call without explicit `locale` and `jurisdiction`.
+- No assistant answer without at least one citation referencing a **KB snapshot**.
+- Snapshot publishing includes only approved rule versions and is jurisdiction-scoped.
+- High-risk KB changes require expert approval.
+
+### What is stubbed vs real
+
+- **LLM**: stubbed/deterministic (no external calls). Answers are derived from KB search results.
+- **Source fetching**: stubbed/offline fixtures (no web truth).
+- **Storage**: in tests, in-memory stores; in sandbox, browser SQLite + IndexedDB.
+
+

package/README.md

@@ -0,0 +1,12 @@
+# `@lssm/example.policy-safe-knowledge-assistant`
+
+All-in-one template example demonstrating a **policy-safe knowledge assistant** end-to-end:
+
+- Locale + jurisdiction gating (fail-closed)
+- Versioned curated KB + published snapshots
+- Automated KB update pipeline with HITL review + traceability
+- Learning hub (drills, ambient coach, quests)
+- Cross-cutting modules wired: identity/RBAC, audit trail, notifications, jobs, feature flags, files, metering, learning journey
+
+This package is the **spec-first** source of truth. The sandbox UI/runtime integration lives in `@lssm/bundle.contractspec-studio`.\n+\n+## Seed scenario\n+\n+See `src/seed/fixtures.ts` for deterministic offline fixtures (no web dependencies).\n+\n+## Running tests\n+\n+```bash\n+bun test\n+```\n+
+

package/dist/docs/index.js

@@ -0,0 +1 @@
+import"./policy-safe-knowledge-assistant.docblock.js";

package/dist/docs/policy-safe-knowledge-assistant.docblock.js

@@ -0,0 +1,14 @@
+import{registerDocBlocks as e}from"@lssm/lib.contracts/docs";e([{id:`docs.examples.policy-safe-knowledge-assistant.goal`,title:`Policy-safe Knowledge Assistant — Goal`,summary:`End-to-end example: versioned KB snapshots + locale/jurisdiction gating + HITL pipeline + learning hub.`,kind:`goal`,visibility:`public`,route:`/docs/examples/policy-safe-knowledge-assistant/goal`,tags:[`assistant`,`knowledge`,`policy`,`hitl`,`learning`],body:`## What this template proves
+- Assistant answers are structured and must cite a KB snapshot (or refuse).
+- Locale + jurisdiction are mandatory inputs for every assistant call.
+- Automation proposes KB patches; humans verify; publishing stays blocked until approvals.
+- Learning hub demonstrates drills + coaching + quests without spam.
+
+## Offline-first
+- Seeded fixtures are deterministic and require no external services.
+- Optional non-authoritative fallback can be added behind a single feature flag (disabled by default).`},{id:`docs.examples.policy-safe-knowledge-assistant.usage`,title:`Policy-safe Knowledge Assistant — Usage`,summary:`5–10 minute sandbox walkthrough for developers.`,kind:`usage`,visibility:`public`,route:`/docs/examples/policy-safe-knowledge-assistant/usage`,tags:[`assistant`,`knowledge`,`usage`],body:`## Demo walkthrough (high level)
+1) Onboard: set locale + jurisdiction.
+2) Publish snapshot: ingest source -> propose rule -> approve -> publish.
+3) Ask assistant: must pass gate and cite snapshot.
+4) Simulate change: watcher -> review -> publish new snapshot.
+5) Learning hub: drills session, ambient tip, quest start + step completion.`}]);

package/dist/example.js

@@ -0,0 +1 @@
+var e={id:`policy-safe-knowledge-assistant`,title:`Policy-safe Knowledge Assistant`,summary:`All-in-one template: locale/jurisdiction gating + versioned KB snapshots + HITL update pipeline + learning hub.`,tags:[`assistant`,`knowledge`,`policy`,`hitl`,`learning`],kind:`template`,visibility:`public`,docs:{goalDocId:`docs.examples.policy-safe-knowledge-assistant.goal`,usageDocId:`docs.examples.policy-safe-knowledge-assistant.usage`},entrypoints:{packageName:`@lssm/example.policy-safe-knowledge-assistant`,feature:`./feature`,docs:`./docs`},surfaces:{templates:!0,sandbox:{enabled:!0,modes:[`playground`,`specs`,`builder`,`markdown`,`evolution`]},studio:{enabled:!0,installable:!0},mcp:{enabled:!0}}};export{e as default};

package/dist/feature.js

@@ -0,0 +1 @@
+const e={meta:{key:`policy-safe-knowledge-assistant`,title:`Policy-safe Knowledge Assistant`,description:`All-in-one example composing locale/jurisdiction gate + versioned KB + HITL pipeline + learning hub.`,domain:`knowledge`,owners:[`examples`],tags:[`assistant`,`knowledge`,`policy`,`hitl`,`learning`],stability:`experimental`},operations:[{name:`assistant.answer`,version:1},{name:`assistant.explainConcept`,version:1},{name:`kb.ingestSource`,version:1},{name:`kb.upsertRuleVersion`,version:1},{name:`kb.approveRuleVersion`,version:1},{name:`kb.publishSnapshot`,version:1},{name:`kb.search`,version:1},{name:`kbPipeline.runWatch`,version:1},{name:`kbPipeline.createReviewTask`,version:1},{name:`kbPipeline.submitDecision`,version:1},{name:`kbPipeline.publishIfReady`,version:1}],events:[{name:`assistant.answer.requested`,version:1},{name:`assistant.answer.blocked`,version:1},{name:`assistant.answer.delivered`,version:1},{name:`kb.source.ingested`,version:1},{name:`kb.ruleVersion.created`,version:1},{name:`kb.ruleVersion.approved`,version:1},{name:`kb.snapshot.published`,version:1},{name:`kb.change.detected`,version:1},{name:`kb.review.requested`,version:1},{name:`kb.review.decided`,version:1}],presentations:[],opToPresentation:[],presentationsTargets:[],capabilities:{requires:[{key:`identity`,version:1},{key:`audit-trail`,version:1},{key:`notifications`,version:1},{key:`jobs`,version:1},{key:`feature-flags`,version:1},{key:`files`,version:1},{key:`metering`,version:1},{key:`learning-journey`,version:1}]}};export{e as PolicySafeKnowledgeAssistantFeature};

package/dist/index.js

@@ -0,0 +1 @@
+import e from"./example.js";import{PolicySafeKnowledgeAssistantFeature as t}from"./feature.js";import{DEMO_FIXTURES as n}from"./seed/fixtures.js";import{buildPolicySafeAnswer as r}from"./orchestrator/buildAnswer.js";import"./docs/index.js";export{n as DEMO_FIXTURES,t as PolicySafeKnowledgeAssistantFeature,r as buildPolicySafeAnswer,e as example};

package/dist/orchestrator/buildAnswer.js

@@ -0,0 +1 @@
+import{enforceAllowedScope as e,enforceCitations as t,validateEnvelope as n}from"@lssm/example.locale-jurisdiction-gate/policy/guard";async function r(r){let i=n(r.envelope);if(!i.ok)return{locale:r.envelope.locale??`en-GB`,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=await r.kbSearch({snapshotId:i.value.kbSnapshotId,jurisdiction:i.value.regulatoryContext.jurisdiction,query:r.question}),o=a.items.map(e=>({kbSnapshotId:i.value.kbSnapshotId,sourceType:`ruleVersion`,sourceId:e.ruleVersionId,title:`Curated rule version`,excerpt:e.excerpt})),s={locale:i.value.locale,jurisdiction:i.value.regulatoryContext.jurisdiction,allowedScope:i.value.allowedScope,sections:[{heading:`Answer (KB-derived)`,body:a.items.length>0?`This answer is derived from ${a.items.length} curated rule version(s) in the referenced snapshot.`:`No curated knowledge found in the referenced snapshot.`}],citations:o,disclaimers:[`Educational demo only.`],riskFlags:[]},c=e(i.value.allowedScope,s);if(!c.ok)return{...s,sections:[{heading:`Escalation required`,body:c.error.message}],refused:!0,refusalReason:c.error.code,riskFlags:[...s.riskFlags??[],c.error.code]};let l=t(s);return l.ok?s:{...s,sections:[{heading:`Request blocked`,body:l.error.message}],citations:[],refused:!0,refusalReason:l.error.code,riskFlags:[...s.riskFlags??[],l.error.code]}}export{r as buildPolicySafeAnswer};

package/dist/seed/fixtures.js

@@ -0,0 +1 @@
+const e={jurisdictions:[`EU`,`FR`],locales:[`en-GB`,`fr-FR`],demoOrgId:`org_demo`,demoUserId:`user_demo`,sources:{EU_SOURCE_1:{jurisdiction:`EU`,authority:`DemoAuthority`,title:`EU Demo Source v1`,fetchedAt:new Date(`2026-01-01T00:00:00.000Z`),hash:`hash_eu_v1`,fileId:`file_eu_v1`},EU_SOURCE_2:{jurisdiction:`EU`,authority:`DemoAuthority`,title:`EU Demo Source v2`,fetchedAt:new Date(`2026-02-01T00:00:00.000Z`),hash:`hash_eu_v2`,fileId:`file_eu_v2`}},rules:{EU_RULE_TAX:{id:`rule_eu_tax`,jurisdiction:`EU`,topicKey:`tax_reporting`}}};export{e as DEMO_FIXTURES};

package/dist/seed/index.js

@@ -0,0 +1 @@
+import{DEMO_FIXTURES as e}from"./fixtures.js";export{e as DEMO_FIXTURES};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@lssm/example.policy-safe-knowledge-assistant",
+  "version": "0.0.0-canary-20251213172311",
+  "description": "All-in-one template example: policy-safe knowledge assistant with locale/jurisdiction gating, versioned KB snapshots, HITL update pipeline, and learning hub.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/policy-safe-knowledge-assistant.docblock": "./src/docs/policy-safe-knowledge-assistant.docblock.ts",
+    "./example": "./src/example.ts",
+    "./feature": "./src/feature.ts",
+    "./orchestrator/buildAnswer": "./src/orchestrator/buildAnswer.ts",
+    "./seed": "./src/seed/index.ts",
+    "./seed/fixtures": "./src/seed/fixtures.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/example.locale-jurisdiction-gate": "workspace:*",
+    "@lssm/example.versioned-knowledge-base": "workspace:*",
+    "@lssm/example.kb-update-pipeline": "workspace:*",
+    "@lssm/example.learning-patterns": "workspace:*",
+    "@lssm/lib.contracts": "workspace:*",
+    "@lssm/lib.identity-rbac": "workspace:*",
+    "@lssm/lib.jobs": "workspace:*",
+    "@lssm/lib.feature-flags": "workspace:*",
+    "@lssm/lib.files": "workspace:*",
+    "@lssm/lib.metering": "workspace:*",
+    "@lssm/module.audit-trail": "workspace:*",
+    "@lssm/module.notifications": "workspace:*",
+    "@lssm/module.learning-journey": "workspace:*"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/policy-safe-knowledge-assistant.docblock": "./dist/docs/policy-safe-knowledge-assistant.docblock.js",
+      "./example": "./dist/example.js",
+      "./feature": "./dist/feature.js",
+      "./orchestrator/buildAnswer": "./dist/orchestrator/buildAnswer.js",
+      "./seed": "./dist/seed/index.js",
+      "./seed/fixtures": "./dist/seed/fixtures.js",
+      "./*": "./*"
+    }
+  }
+}

package/src/docs/index.ts

@@ -0,0 +1,3 @@
+import './policy-safe-knowledge-assistant.docblock';
+
+

package/src/docs/policy-safe-knowledge-assistant.docblock.ts

@@ -0,0 +1,30 @@
+import type { DocBlock } from '@lssm/lib.contracts/docs';
+import { registerDocBlocks } from '@lssm/lib.contracts/docs';
+
+const docBlocks: DocBlock[] = [
+  {
+    id: 'docs.examples.policy-safe-knowledge-assistant.goal',
+    title: 'Policy-safe Knowledge Assistant — Goal',
+    summary:
+      'End-to-end example: versioned KB snapshots + locale/jurisdiction gating + HITL pipeline + learning hub.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/examples/policy-safe-knowledge-assistant/goal',
+    tags: ['assistant', 'knowledge', 'policy', 'hitl', 'learning'],
+    body: `## What this template proves\n- Assistant answers are structured and must cite a KB snapshot (or refuse).\n- Locale + jurisdiction are mandatory inputs for every assistant call.\n- Automation proposes KB patches; humans verify; publishing stays blocked until approvals.\n- Learning hub demonstrates drills + coaching + quests without spam.\n\n## Offline-first\n- Seeded fixtures are deterministic and require no external services.\n- Optional non-authoritative fallback can be added behind a single feature flag (disabled by default).`,
+  },
+  {
+    id: 'docs.examples.policy-safe-knowledge-assistant.usage',
+    title: 'Policy-safe Knowledge Assistant — Usage',
+    summary: '5–10 minute sandbox walkthrough for developers.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/examples/policy-safe-knowledge-assistant/usage',
+    tags: ['assistant', 'knowledge', 'usage'],
+    body: `## Demo walkthrough (high level)\n1) Onboard: set locale + jurisdiction.\n2) Publish snapshot: ingest source -> propose rule -> approve -> publish.\n3) Ask assistant: must pass gate and cite snapshot.\n4) Simulate change: watcher -> review -> publish new snapshot.\n5) Learning hub: drills session, ambient tip, quest start + step completion.`,
+  },
+];
+
+registerDocBlocks(docBlocks);
+
+

package/src/example.ts

@@ -0,0 +1,28 @@
+const example = {
+  id: 'policy-safe-knowledge-assistant',
+  title: 'Policy-safe Knowledge Assistant',
+  summary:
+    'All-in-one template: locale/jurisdiction gating + versioned KB snapshots + HITL update pipeline + learning hub.',
+  tags: ['assistant', 'knowledge', 'policy', 'hitl', 'learning'],
+  kind: 'template',
+  visibility: 'public',
+  docs: {
+    goalDocId: 'docs.examples.policy-safe-knowledge-assistant.goal',
+    usageDocId: 'docs.examples.policy-safe-knowledge-assistant.usage',
+  },
+  entrypoints: {
+    packageName: '@lssm/example.policy-safe-knowledge-assistant',
+    feature: './feature',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['playground', 'specs', 'builder', 'markdown', 'evolution'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+} as const;
+
+export default example;
+
+

package/src/feature.ts

@@ -0,0 +1,57 @@
+import type { FeatureModuleSpec } from '@lssm/lib.contracts';
+
+export const PolicySafeKnowledgeAssistantFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'policy-safe-knowledge-assistant',
+    title: 'Policy-safe Knowledge Assistant',
+    description:
+      'All-in-one example composing locale/jurisdiction gate + versioned KB + HITL pipeline + learning hub.',
+    domain: 'knowledge',
+    owners: ['examples'],
+    tags: ['assistant', 'knowledge', 'policy', 'hitl', 'learning'],
+    stability: 'experimental',
+  },
+  operations: [
+    // Gate
+    { name: 'assistant.answer', version: 1 },
+    { name: 'assistant.explainConcept', version: 1 },
+    // KB
+    { name: 'kb.ingestSource', version: 1 },
+    { name: 'kb.upsertRuleVersion', version: 1 },
+    { name: 'kb.approveRuleVersion', version: 1 },
+    { name: 'kb.publishSnapshot', version: 1 },
+    { name: 'kb.search', version: 1 },
+    // Pipeline
+    { name: 'kbPipeline.runWatch', version: 1 },
+    { name: 'kbPipeline.createReviewTask', version: 1 },
+    { name: 'kbPipeline.submitDecision', version: 1 },
+    { name: 'kbPipeline.publishIfReady', version: 1 },
+  ],
+  events: [
+    { name: 'assistant.answer.requested', version: 1 },
+    { name: 'assistant.answer.blocked', version: 1 },
+    { name: 'assistant.answer.delivered', version: 1 },
+    { name: 'kb.source.ingested', version: 1 },
+    { name: 'kb.ruleVersion.created', version: 1 },
+    { name: 'kb.ruleVersion.approved', version: 1 },
+    { name: 'kb.snapshot.published', version: 1 },
+    { name: 'kb.change.detected', version: 1 },
+    { name: 'kb.review.requested', version: 1 },
+    { name: 'kb.review.decided', version: 1 },
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    requires: [
+      { key: 'identity', version: 1 },
+      { key: 'audit-trail', version: 1 },
+      { key: 'notifications', version: 1 },
+      { key: 'jobs', version: 1 },
+      { key: 'feature-flags', version: 1 },
+      { key: 'files', version: 1 },
+      { key: 'metering', version: 1 },
+      { key: 'learning-journey', version: 1 },
+    ],
+  },
+};

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Policy-safe Knowledge Assistant (all-in-one template) — spec-first exports.
+ */
+export * from './feature';
+export * from './seed';
+export * from './orchestrator/buildAnswer';
+export { default as example } from './example';
+
+import './docs';
+
+

package/src/integration.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createMemoryKbHandlers, createMemoryKbStore } from '@lssm/example.versioned-knowledge-base/handlers/memory.handlers';
+import { createPipelineMemoryHandlers, createPipelineMemoryStore } from '@lssm/example.kb-update-pipeline/handlers/memory.handlers';
+
+import { buildPolicySafeAnswer } from './orchestrator/buildAnswer';
+import { DEMO_FIXTURES } from './seed/fixtures';
+
+describe('@lssm/example.policy-safe-knowledge-assistant integration', () => {
+  it('answers cite latest snapshot; after pipeline change + publish, answers cite new snapshot', async () => {
+    const kbStore = createMemoryKbStore();
+    const kb = createMemoryKbHandlers(kbStore);
+
+    const pipelineStore = createPipelineMemoryStore();
+    const pipeline = createPipelineMemoryHandlers(pipelineStore);
+
+    // Seed rules
+    await kb.createRule(DEMO_FIXTURES.rules.EU_RULE_TAX);
+
+    // Publish initial snapshot (EU v1)
+    const rv1 = await kb.upsertRuleVersion({
+      ruleId: DEMO_FIXTURES.rules.EU_RULE_TAX.id,
+      content: 'EU: Reporting obligations v1',
+      sourceRefs: [{ sourceDocumentId: 'src_eu_v1', excerpt: 'v1 excerpt' }],
+    });
+    await kb.approveRuleVersion({ ruleVersionId: rv1.id, approver: 'expert_1' });
+    const snap1 = await kb.publishSnapshot({
+      jurisdiction: 'EU',
+      asOfDate: new Date('2026-01-01T00:00:00.000Z'),
+    });
+
+    const envelopeBase = {
+      traceId: 'trace_1',
+      locale: 'en-GB',
+      regulatoryContext: { jurisdiction: 'EU' },
+      allowedScope: 'education_only' as const,
+    };
+
+    const a1 = await buildPolicySafeAnswer({
+      envelope: { ...envelopeBase, kbSnapshotId: snap1.id },
+      question: 'reporting obligations',
+      kbSearch: kb.search,
+    });
+
+    expect(a1.refused).not.toBeTrue();
+    expect(a1.citations.length).toBeGreaterThan(0);
+    expect(a1.citations[0]?.kbSnapshotId).toBe(snap1.id);
+
+    // Simulate regulatory change via pipeline: create candidate, review, propose patch
+    pipelineStore.candidates.set('cand_1', {
+      id: 'cand_1',
+      sourceDocumentId: 'EU_src_change',
+      detectedAt: new Date('2026-02-01T00:00:00.000Z'),
+      diffSummary: 'Updated obligations',
+      riskLevel: 'high',
+    });
+    const review = await pipeline.createReviewTask({ changeCandidateId: 'cand_1' });
+    await pipeline.submitDecision({
+      reviewTaskId: review.id,
+      decision: 'approve',
+      decidedBy: 'expert_2',
+      decidedByRole: 'expert',
+    });
+
+    // Create + approve new KB rule version
+    const rv2 = await kb.upsertRuleVersion({
+      ruleId: DEMO_FIXTURES.rules.EU_RULE_TAX.id,
+      content: 'EU: Reporting obligations v2 (updated)',
+      sourceRefs: [{ sourceDocumentId: 'src_eu_v2', excerpt: 'v2 excerpt' }],
+    });
+    await kb.approveRuleVersion({ ruleVersionId: rv2.id, approver: 'expert_2' });
+
+    // Link pipeline proposal to the actual KB rule version id, then mark it approved
+    await pipeline.proposeRulePatch({
+      changeCandidateId: 'cand_1',
+      proposedRuleVersionIds: [rv2.id],
+    });
+    await pipeline.markRuleVersionApproved({ ruleVersionId: rv2.id });
+    await pipeline.publishIfReady({ jurisdiction: 'EU' });
+
+    const snap2 = await kb.publishSnapshot({
+      jurisdiction: 'EU',
+      asOfDate: new Date('2026-02-01T00:00:00.000Z'),
+    });
+
+    const a2 = await buildPolicySafeAnswer({
+      envelope: { ...envelopeBase, kbSnapshotId: snap2.id },
+      question: 'updated obligations',
+      kbSearch: kb.search,
+    });
+    expect(a2.refused).not.toBeTrue();
+    expect(a2.citations[0]?.kbSnapshotId).toBe(snap2.id);
+  });
+});
+
+

package/src/orchestrator/buildAnswer.ts

@@ -0,0 +1,124 @@
+import {
+  enforceAllowedScope,
+  enforceCitations,
+  validateEnvelope,
+} from '@lssm/example.locale-jurisdiction-gate/policy/guard';
+
+type AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';
+
+export type AssistantAnswerIR = {
+  locale: string;
+  jurisdiction: string;
+  allowedScope: AllowedScope;
+  sections: Array<{ heading: string; body: string }>;
+  citations: Array<{
+    kbSnapshotId: string;
+    sourceType: string;
+    sourceId: string;
+    title?: string;
+    excerpt?: string;
+  }>;
+  disclaimers?: string[];
+  riskFlags?: string[];
+  refused?: boolean;
+  refusalReason?: string;
+};
+
+export interface BuildAnswerInput {
+  envelope: {
+    traceId: string;
+    locale: string;
+    kbSnapshotId: string;
+    allowedScope: AllowedScope;
+    regulatoryContext: { jurisdiction: string };
+  };
+  question: string;
+  kbSearch: (input: {
+    snapshotId: string;
+    jurisdiction: string;
+    query: string;
+  }) => Promise<{ items: Array<{ ruleVersionId: string; excerpt?: string }> }>;
+}
+
+/**
+ * Build a policy-safe assistant answer derived from KB search results.
+ *
+ * Deterministic: no LLM calls; if search yields no results, it refuses.
+ */
+export async function buildPolicySafeAnswer(
+  input: BuildAnswerInput
+): Promise<AssistantAnswerIR> {
+  const env = validateEnvelope(input.envelope);
+  if (!env.ok) {
+    return {
+      locale: input.envelope.locale ?? 'en-GB',
+      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 results = await input.kbSearch({
+    snapshotId: env.value.kbSnapshotId,
+    jurisdiction: env.value.regulatoryContext!.jurisdiction!,
+    query: input.question,
+  });
+
+  const citations = results.items.map((item) => ({
+    kbSnapshotId: env.value.kbSnapshotId,
+    sourceType: 'ruleVersion',
+    sourceId: item.ruleVersionId,
+    title: 'Curated rule version',
+    excerpt: item.excerpt,
+  }));
+
+  const draft: AssistantAnswerIR = {
+    locale: env.value.locale,
+    jurisdiction: env.value.regulatoryContext!.jurisdiction!,
+    allowedScope: env.value.allowedScope,
+    sections: [
+      {
+        heading: 'Answer (KB-derived)',
+        body:
+          results.items.length > 0
+            ? `This answer is derived from ${results.items.length} curated rule version(s) in the referenced snapshot.`
+            : 'No curated knowledge found in the referenced snapshot.',
+      },
+    ],
+    citations,
+    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 }],
+      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;
+}
+
+

package/src/seed/fixtures.ts

@@ -0,0 +1,33 @@
+export const DEMO_FIXTURES = {
+  jurisdictions: ['EU', 'FR'] as const,
+  locales: ['en-GB', 'fr-FR'] as const,
+  demoOrgId: 'org_demo',
+  demoUserId: 'user_demo',
+  sources: {
+    EU_SOURCE_1: {
+      jurisdiction: 'EU',
+      authority: 'DemoAuthority',
+      title: 'EU Demo Source v1',
+      fetchedAt: new Date('2026-01-01T00:00:00.000Z'),
+      hash: 'hash_eu_v1',
+      fileId: 'file_eu_v1',
+    },
+    EU_SOURCE_2: {
+      jurisdiction: 'EU',
+      authority: 'DemoAuthority',
+      title: 'EU Demo Source v2',
+      fetchedAt: new Date('2026-02-01T00:00:00.000Z'),
+      hash: 'hash_eu_v2',
+      fileId: 'file_eu_v2',
+    },
+  },
+  rules: {
+    EU_RULE_TAX: {
+      id: 'rule_eu_tax',
+      jurisdiction: 'EU',
+      topicKey: 'tax_reporting',
+    },
+  },
+} as const;
+
+

package/src/seed/index.ts

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

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@lssm/tool.typescript/react-library.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+
+