@lssm/example.versioned-knowledge-base 0.0.0-canary-20251213172311

package/src/feature.ts

@@ -0,0 +1,35 @@
+import type { FeatureModuleSpec } from '@lssm/lib.contracts';
+
+export const VersionedKnowledgeBaseFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'versioned-knowledge-base',
+    title: 'Versioned Knowledge Base',
+    description:
+      'Curated KB with immutable sources, rule versions, and published snapshots.',
+    domain: 'knowledge',
+    owners: ['examples'],
+    tags: ['knowledge', 'versioning', 'snapshots'],
+    stability: 'experimental',
+  },
+  operations: [
+    { 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 },
+  ],
+  events: [
+    { name: 'kb.source.ingested', version: 1 },
+    { name: 'kb.ruleVersion.created', version: 1 },
+    { name: 'kb.ruleVersion.approved', version: 1 },
+    { name: 'kb.snapshot.published', version: 1 },
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    requires: [{ key: 'knowledge', version: 1 }],
+  },
+};
+
+

package/src/handlers/index.ts

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

package/src/handlers/memory.handlers.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createMemoryKbHandlers, createMemoryKbStore } from './memory.handlers';
+
+describe('@lssm/example.versioned-knowledge-base memory handlers', () => {
+  it('requires sourceRefs for rule versions (traceability)', async () => {
+    const store = createMemoryKbStore();
+    const kb = createMemoryKbHandlers(store);
+    await kb.createRule({ id: 'rule_1', jurisdiction: 'EU', topicKey: 't1' });
+    await expect(
+      kb.upsertRuleVersion({ ruleId: 'rule_1', content: 'x', sourceRefs: [] })
+    ).rejects.toThrow('SOURCE_REFS_REQUIRED');
+  });
+
+  it('snapshot includes only approved rule versions for that jurisdiction', async () => {
+    const store = createMemoryKbStore();
+    const kb = createMemoryKbHandlers(store);
+
+    await kb.createRule({ id: 'rule_eu', jurisdiction: 'EU', topicKey: 'tax' });
+    await kb.createRule({ id: 'rule_fr', jurisdiction: 'FR', topicKey: 'tax' });
+
+    const euDraft = await kb.upsertRuleVersion({
+      ruleId: 'rule_eu',
+      content: 'EU rule content',
+      sourceRefs: [{ sourceDocumentId: 'src1' }],
+    });
+    const frDraft = await kb.upsertRuleVersion({
+      ruleId: 'rule_fr',
+      content: 'FR rule content',
+      sourceRefs: [{ sourceDocumentId: 'src2' }],
+    });
+
+    const euApproved = await kb.approveRuleVersion({
+      ruleVersionId: euDraft.id,
+      approver: 'expert_1',
+    });
+    await kb.approveRuleVersion({
+      ruleVersionId: frDraft.id,
+      approver: 'expert_1',
+    });
+
+    const snapshot = await kb.publishSnapshot({
+      jurisdiction: 'EU',
+      asOfDate: new Date('2026-01-01T00:00:00.000Z'),
+    });
+
+    expect(snapshot.includedRuleVersionIds).toEqual([euApproved.id]);
+  });
+
+  it('search is scoped to snapshot + jurisdiction', async () => {
+    const store = createMemoryKbStore();
+    const kb = createMemoryKbHandlers(store);
+
+    await kb.createRule({ id: 'rule_eu', jurisdiction: 'EU', topicKey: 'topic' });
+    const euDraft = await kb.upsertRuleVersion({
+      ruleId: 'rule_eu',
+      content: 'This is about reporting obligations',
+      sourceRefs: [{ sourceDocumentId: 'src1' }],
+    });
+    await kb.approveRuleVersion({ ruleVersionId: euDraft.id, approver: 'u1' });
+    const snap = await kb.publishSnapshot({
+      jurisdiction: 'EU',
+      asOfDate: new Date('2026-01-01T00:00:00.000Z'),
+    });
+
+    await expect(
+      kb.search({ snapshotId: snap.id, jurisdiction: 'FR', query: 'reporting' })
+    ).rejects.toThrow('JURISDICTION_MISMATCH');
+
+    const ok = await kb.search({
+      snapshotId: snap.id,
+      jurisdiction: 'EU',
+      query: 'reporting',
+    });
+    expect(ok.items.map((i) => i.ruleVersionId)).toEqual([euDraft.id]);
+  });
+});
+
+

package/src/handlers/memory.handlers.ts

@@ -0,0 +1,206 @@
+type SourceRef = { sourceDocumentId: string; excerpt?: string };
+type SourceDocument = {
+  id: string;
+  jurisdiction: string;
+  authority: string;
+  title: string;
+  fetchedAt: Date;
+  hash: string;
+  fileId: string;
+};
+type Rule = { id: string; jurisdiction: string; topicKey: string };
+type RuleVersion = {
+  id: string;
+  ruleId: string;
+  jurisdiction: string;
+  topicKey: string;
+  version: number;
+  content: string;
+  sourceRefs: SourceRef[];
+  status: 'draft' | 'approved' | 'rejected';
+  approvedBy?: string;
+  approvedAt?: Date;
+  createdAt: Date;
+};
+type KBSnapshot = {
+  id: string;
+  jurisdiction: string;
+  asOfDate: Date;
+  includedRuleVersionIds: string[];
+  publishedAt: Date;
+};
+
+export interface MemoryKbStore {
+  sources: Map<string, SourceDocument>;
+  rules: Map<string, Rule>;
+  ruleVersions: Map<string, RuleVersion>;
+  snapshots: Map<string, KBSnapshot>;
+  nextRuleVersionNumberByRuleId: Map<string, number>;
+}
+
+export function createMemoryKbStore(): MemoryKbStore {
+  return {
+    sources: new Map(),
+    rules: new Map(),
+    ruleVersions: new Map(),
+    snapshots: new Map(),
+    nextRuleVersionNumberByRuleId: new Map(),
+  };
+}
+
+export interface MemoryKbHandlers {
+  createRule(rule: Rule): Promise<Rule>;
+  ingestSource(input: Omit<SourceDocument, 'id'>): Promise<SourceDocument>;
+  upsertRuleVersion(input: {
+    ruleId: string;
+    content: string;
+    sourceRefs: SourceRef[];
+  }): Promise<RuleVersion>;
+  approveRuleVersion(input: {
+    ruleVersionId: string;
+    approver: string;
+  }): Promise<RuleVersion>;
+  publishSnapshot(input: {
+    jurisdiction: string;
+    asOfDate: Date;
+  }): Promise<KBSnapshot>;
+  search(input: {
+    snapshotId: string;
+    jurisdiction: string;
+    query: string;
+  }): Promise<{ items: Array<{ ruleVersionId: string; excerpt?: string }> }>;
+}
+
+function stableId(prefix: string, value: string): string {
+  return `${prefix}_${value.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+}
+
+export function createMemoryKbHandlers(store: MemoryKbStore): MemoryKbHandlers {
+  async function createRule(rule: Rule): Promise<Rule> {
+    store.rules.set(rule.id, rule);
+    return rule;
+  }
+
+  async function ingestSource(
+    input: Omit<SourceDocument, 'id'>
+  ): Promise<SourceDocument> {
+    const id = stableId('src', `${input.jurisdiction}_${input.hash}`);
+    const doc: SourceDocument = { id, ...input };
+    store.sources.set(id, doc);
+    return doc;
+  }
+
+  async function upsertRuleVersion(input: {
+    ruleId: string;
+    content: string;
+    sourceRefs: SourceRef[];
+  }): Promise<RuleVersion> {
+    if (!input.sourceRefs.length) {
+      throw new Error('SOURCE_REFS_REQUIRED');
+    }
+    const rule = store.rules.get(input.ruleId);
+    if (!rule) {
+      throw new Error('RULE_NOT_FOUND');
+    }
+    const next =
+      (store.nextRuleVersionNumberByRuleId.get(input.ruleId) ?? 0) + 1;
+    store.nextRuleVersionNumberByRuleId.set(input.ruleId, next);
+    const id = stableId('rv', `${input.ruleId}_${next}`);
+    const ruleVersion: RuleVersion = {
+      id,
+      ruleId: input.ruleId,
+      jurisdiction: rule.jurisdiction,
+      topicKey: rule.topicKey,
+      version: next,
+      content: input.content,
+      sourceRefs: input.sourceRefs,
+      status: 'draft',
+      createdAt: new Date(),
+      approvedAt: undefined,
+      approvedBy: undefined,
+    };
+    store.ruleVersions.set(id, ruleVersion);
+    return ruleVersion;
+  }
+
+  async function approveRuleVersion(input: {
+    ruleVersionId: string;
+    approver: string;
+  }): Promise<RuleVersion> {
+    const existing = store.ruleVersions.get(input.ruleVersionId);
+    if (!existing) {
+      throw new Error('RULE_VERSION_NOT_FOUND');
+    }
+    const approved: RuleVersion = {
+      ...existing,
+      status: 'approved',
+      approvedBy: input.approver,
+      approvedAt: new Date(),
+    };
+    store.ruleVersions.set(approved.id, approved);
+    return approved;
+  }
+
+  async function publishSnapshot(input: {
+    jurisdiction: string;
+    asOfDate: Date;
+  }): Promise<KBSnapshot> {
+    const approved = [...store.ruleVersions.values()].filter(
+      (rv) => rv.status === 'approved' && rv.jurisdiction === input.jurisdiction
+    );
+    if (approved.length === 0) {
+      throw new Error('NO_APPROVED_RULES');
+    }
+    const includedRuleVersionIds = approved.map((rv) => rv.id).sort();
+    const id = stableId(
+      'snap',
+      `${input.jurisdiction}_${input.asOfDate.toISOString().slice(0, 10)}_${includedRuleVersionIds.length}`
+    );
+    const snapshot: KBSnapshot = {
+      id,
+      jurisdiction: input.jurisdiction,
+      asOfDate: input.asOfDate,
+      includedRuleVersionIds,
+      publishedAt: new Date(),
+    };
+    store.snapshots.set(id, snapshot);
+    return snapshot;
+  }
+
+  async function search(input: {
+    snapshotId: string;
+    jurisdiction: string;
+    query: string;
+  }): Promise<{ items: Array<{ ruleVersionId: string; excerpt?: string }> }> {
+    const snapshot = store.snapshots.get(input.snapshotId);
+    if (!snapshot) {
+      throw new Error('SNAPSHOT_NOT_FOUND');
+    }
+    if (snapshot.jurisdiction !== input.jurisdiction) {
+      throw new Error('JURISDICTION_MISMATCH');
+    }
+    const q = input.query.toLowerCase();
+    const tokens = q.split(/\s+/).map((t) => t.trim()).filter(Boolean);
+    const items = snapshot.includedRuleVersionIds
+      .map((id) => store.ruleVersions.get(id))
+      .filter((rv): rv is RuleVersion => Boolean(rv))
+      .filter((rv) => {
+        if (tokens.length === 0) return true;
+        const hay = rv.content.toLowerCase();
+        return tokens.every((token) => hay.includes(token));
+      })
+      .map((rv) => ({ ruleVersionId: rv.id, excerpt: rv.content.slice(0, 120) }));
+    return { items };
+  }
+
+  return {
+    createRule,
+    ingestSource,
+    upsertRuleVersion,
+    approveRuleVersion,
+    publishSnapshot,
+    search,
+  };
+}
+
+

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Versioned Knowledge Base Example
+ *
+ * Curated KB with immutable sources, reviewable rule versions, and published snapshots.
+ */
+export * from './entities';
+export * from './contracts';
+export * from './events';
+export * from './handlers';
+export * from './feature';
+export { default as example } from './example';
+
+import './docs';
+
+

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"]
+}
+
+