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

package/.turbo/turbo-build.log

@@ -0,0 +1,23 @@
+$ 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/versioned-knowledge-base/tsdown.config.js 
+ℹ entry: src/events.ts, src/example.ts, src/feature.ts, src/index.ts, src/contracts/index.ts, src/contracts/kb.ts, src/docs/index.ts, src/docs/versioned-knowledge-base.docblock.ts, src/entities/index.ts, src/entities/models.ts, src/handlers/index.ts, src/handlers/memory.handlers.ts
+ℹ target: esnext
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ dist/contracts/kb.js                            4.35 kB │ gzip: 1.33 kB
+ℹ dist/handlers/memory.handlers.js                2.16 kB │ gzip: 0.91 kB
+ℹ dist/entities/models.js                         2.13 kB │ gzip: 0.59 kB
+ℹ dist/events.js                                  1.72 kB │ gzip: 0.49 kB
+ℹ dist/docs/versioned-knowledge-base.docblock.js  1.28 kB │ gzip: 0.59 kB
+ℹ dist/index.js                                   1.21 kB │ gzip: 0.42 kB
+ℹ dist/feature.js                                 0.81 kB │ gzip: 0.37 kB
+ℹ dist/example.js                                 0.61 kB │ gzip: 0.36 kB
+ℹ dist/contracts/index.js                         0.33 kB │ gzip: 0.16 kB
+ℹ dist/entities/index.js                          0.24 kB │ gzip: 0.14 kB
+ℹ dist/handlers/index.js                          0.15 kB │ gzip: 0.10 kB
+ℹ dist/docs/index.js                              0.05 kB │ gzip: 0.07 kB
+ℹ 12 files, total: 15.02 kB
+✔ Build complete in 66ms
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @lssm/example.versioned-knowledge-base
+
+## 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,24 @@
+# `@lssm/example.versioned-knowledge-base`
+
+Spec-first example demonstrating a **curated, versioned knowledge base**:
+
+- Raw **source documents** are immutable and referenced by hash.
+- Curated **rules** are versioned, reviewable, and must cite sources.
+- Published **KB snapshots** contain only **approved** rule versions.
+- Assistant answers reference a **snapshot id** for traceability.
+
+## Contracts
+
+- `kb.ingestSource(docMeta, fileRef) -> SourceDocument`
+- `kb.upsertRuleVersion(ruleId, content, sourceRefs) -> RuleVersion (draft)`
+- `kb.approveRuleVersion(ruleVersionId, approver) -> RuleVersion (approved)`
+- `kb.publishSnapshot(jurisdiction, asOfDate) -> KBSnapshot`
+- `kb.search(snapshotId, query) -> results (ruleVersionIds + citations)`
+
+## Running tests
+
+```bash
+bun test
+```
+
+

package/dist/contracts/index.js

@@ -0,0 +1 @@
+import{KbApproveRuleVersionContract as e,KbIngestSourceContract as t,KbPublishSnapshotContract as n,KbSearchContract as r,KbUpsertRuleVersionContract as i}from"./kb.js";export{e as KbApproveRuleVersionContract,t as KbIngestSourceContract,n as KbPublishSnapshotContract,r as KbSearchContract,i as KbUpsertRuleVersionContract};

package/dist/contracts/kb.js

@@ -0,0 +1 @@
+import{KBSnapshotModel as e,RuleVersionModel as t,SourceDocumentModel as n,SourceRefModel as r}from"../entities/models.js";import{defineCommand as i,defineQuery as a}from"@lssm/lib.contracts";import{ScalarTypeEnum as o,defineSchemaModel as s}from"@lssm/lib.schema";const c=s({name:`KbIngestSourceInput`,description:`Ingest immutable source metadata referencing a stored file.`,fields:{jurisdiction:{type:o.String_unsecure(),isOptional:!1},authority:{type:o.String_unsecure(),isOptional:!1},title:{type:o.String_unsecure(),isOptional:!1},fetchedAt:{type:o.DateTime(),isOptional:!1},hash:{type:o.String_unsecure(),isOptional:!1},fileId:{type:o.String_unsecure(),isOptional:!1}}}),l=s({name:`KbUpsertRuleVersionInput`,description:`Create a new draft rule version (immutable history).`,fields:{ruleId:{type:o.String_unsecure(),isOptional:!1},content:{type:o.String_unsecure(),isOptional:!1},sourceRefs:{type:r,isArray:!0,isOptional:!1}}}),u=s({name:`KbApproveRuleVersionInput`,description:`Approve a rule version (human verification).`,fields:{ruleVersionId:{type:o.String_unsecure(),isOptional:!1},approver:{type:o.String_unsecure(),isOptional:!1}}}),d=s({name:`KbPublishSnapshotInput`,description:`Publish a snapshot for a jurisdiction as-of a date.`,fields:{jurisdiction:{type:o.String_unsecure(),isOptional:!1},asOfDate:{type:o.DateTime(),isOptional:!1}}}),f=s({name:`KbSearchInput`,description:`Search within a published snapshot.`,fields:{snapshotId:{type:o.String_unsecure(),isOptional:!1},jurisdiction:{type:o.String_unsecure(),isOptional:!1},query:{type:o.String_unsecure(),isOptional:!1}}}),p=s({name:`KbSearchOutput`,description:`Search results constrained to snapshot + jurisdiction.`,fields:{items:{type:s({name:`KbSearchResultItem`,description:`Search result referencing a specific rule version.`,fields:{ruleVersionId:{type:o.String_unsecure(),isOptional:!1},excerpt:{type:o.String_unsecure(),isOptional:!0}}}),isArray:!0,isOptional:!1}}}),m=i({meta:{name:`kb.ingestSource`,version:1,stability:`experimental`,owners:[`examples`],tags:[`knowledge`,`sources`,`ingestion`],description:`Ingest immutable source document metadata.`,goal:`Store traceable source documents for curated KB.`,context:`Called when an admin uploads/records authoritative sources.`},io:{input:c,output:n},policy:{auth:`user`}}),h=i({meta:{name:`kb.upsertRuleVersion`,version:1,stability:`experimental`,owners:[`examples`],tags:[`knowledge`,`rules`,`versioning`],description:`Create a new draft rule version with source references.`,goal:`Propose curated knowledge updates with traceability.`,context:`Automation or curators propose draft rule versions.`},io:{input:l,output:t,errors:{SOURCE_REFS_REQUIRED:{description:`Rule version must cite at least one sourceRef`,http:400,gqlCode:`SOURCE_REFS_REQUIRED`,when:`sourceRefs is empty`},RULE_NOT_FOUND:{description:`Rule does not exist`,http:404,gqlCode:`RULE_NOT_FOUND`,when:`ruleId is unknown`}}},policy:{auth:`user`}}),g=i({meta:{name:`kb.approveRuleVersion`,version:1,stability:`experimental`,owners:[`examples`],tags:[`knowledge`,`rules`,`approval`],description:`Approve a draft rule version.`,goal:`Human verification step before publishing snapshots.`,context:`Curators/experts approve proposed KB changes.`},io:{input:u,output:t},policy:{auth:`user`}}),_=i({meta:{name:`kb.publishSnapshot`,version:1,stability:`experimental`,owners:[`examples`],tags:[`knowledge`,`snapshots`,`publishing`],description:`Publish a KB snapshot for a jurisdiction.`,goal:`Create a stable snapshot that assistant answers can cite.`,context:`Publishing happens after approvals; snapshot is referenced by answers.`},io:{input:d,output:e,errors:{NO_APPROVED_RULES:{description:`No approved rule versions available to publish`,http:409,gqlCode:`NO_APPROVED_RULES`,when:`jurisdiction has zero approved rule versions`}}},policy:{auth:`user`}}),v=a({meta:{name:`kb.search`,version:1,stability:`experimental`,owners:[`examples`],tags:[`knowledge`,`search`,`snapshots`],description:`Search within a published KB snapshot.`,goal:`Provide scoped retrieval for assistant answers.`,context:`Assistant queries curated rules from a specific snapshot.`},io:{input:f,output:p},policy:{auth:`user`}});export{g as KbApproveRuleVersionContract,m as KbIngestSourceContract,_ as KbPublishSnapshotContract,v as KbSearchContract,h as KbUpsertRuleVersionContract};

package/dist/docs/index.js

@@ -0,0 +1 @@
+import"./versioned-knowledge-base.docblock.js";

package/dist/docs/versioned-knowledge-base.docblock.js

@@ -0,0 +1,20 @@
+import{registerDocBlocks as e}from"@lssm/lib.contracts/docs";e([{id:`docs.examples.versioned-knowledge-base.goal`,title:`Versioned Knowledge Base — Goal`,summary:`Curated KB with immutable sources, versioned rules, and published snapshots referenced by answers.`,kind:`goal`,visibility:`public`,route:`/docs/examples/versioned-knowledge-base/goal`,tags:[`knowledge`,`versioning`,`snapshots`,`traceability`],body:`## Why it matters
+- Separates raw sources from curated knowledge.
+- Ensures assistant answers cite a published snapshot.
+- Makes change review and safe regeneration possible.
+
+## Core invariants
+- Sources are immutable and content-addressed (hash).
+- Rule versions must cite at least one source.
+- Snapshots include only approved rule versions.`},{id:`docs.examples.versioned-knowledge-base.reference`,title:`Versioned Knowledge Base — Reference`,summary:`Entities, contracts, and events for the versioned KB example.`,kind:`reference`,visibility:`public`,route:`/docs/examples/versioned-knowledge-base`,tags:[`knowledge`,`reference`],body:`## Contracts
+- kb.ingestSource
+- kb.upsertRuleVersion
+- kb.approveRuleVersion
+- kb.publishSnapshot
+- kb.search
+
+## Events
+- kb.source.ingested
+- kb.ruleVersion.created
+- kb.ruleVersion.approved
+- kb.snapshot.published`}]);

package/dist/entities/index.js

@@ -0,0 +1 @@
+import{KBSnapshotModel as e,RuleModel as t,RuleVersionModel as n,SourceDocumentModel as r,SourceRefModel as i}from"./models.js";export{e as KBSnapshotModel,t as RuleModel,n as RuleVersionModel,r as SourceDocumentModel,i as SourceRefModel};

package/dist/entities/models.js

@@ -0,0 +1 @@
+import{ScalarTypeEnum as e,defineSchemaModel as t}from"@lssm/lib.schema";const n=t({name:`SourceDocument`,description:`Immutable raw source document metadata referencing a stored file.`,fields:{id:{type:e.String_unsecure(),isOptional:!1},jurisdiction:{type:e.String_unsecure(),isOptional:!1},authority:{type:e.String_unsecure(),isOptional:!1},title:{type:e.String_unsecure(),isOptional:!1},fetchedAt:{type:e.DateTime(),isOptional:!1},hash:{type:e.String_unsecure(),isOptional:!1},fileId:{type:e.String_unsecure(),isOptional:!1}}}),r=t({name:`SourceRef`,description:`Reference to a source document used to justify a rule version.`,fields:{sourceDocumentId:{type:e.String_unsecure(),isOptional:!1},excerpt:{type:e.String_unsecure(),isOptional:!0}}}),i=t({name:`Rule`,description:`Curated rule (stable identity) with topic + jurisdiction scope.`,fields:{id:{type:e.String_unsecure(),isOptional:!1},jurisdiction:{type:e.String_unsecure(),isOptional:!1},topicKey:{type:e.String_unsecure(),isOptional:!1}}}),a=t({name:`RuleVersion`,description:`A versioned rule content with source references and approval status.`,fields:{id:{type:e.String_unsecure(),isOptional:!1},ruleId:{type:e.String_unsecure(),isOptional:!1},jurisdiction:{type:e.String_unsecure(),isOptional:!1},topicKey:{type:e.String_unsecure(),isOptional:!1},version:{type:e.Int_unsecure(),isOptional:!1},content:{type:e.String_unsecure(),isOptional:!1},sourceRefs:{type:r,isArray:!0,isOptional:!1},status:{type:e.String_unsecure(),isOptional:!1},approvedBy:{type:e.String_unsecure(),isOptional:!0},approvedAt:{type:e.DateTime(),isOptional:!0},createdAt:{type:e.DateTime(),isOptional:!1}}}),o=t({name:`KBSnapshot`,description:`Published KB snapshot (as-of) referencing approved rule versions.`,fields:{id:{type:e.String_unsecure(),isOptional:!1},jurisdiction:{type:e.String_unsecure(),isOptional:!1},asOfDate:{type:e.DateTime(),isOptional:!1},includedRuleVersionIds:{type:e.String_unsecure(),isArray:!0,isOptional:!1},publishedAt:{type:e.DateTime(),isOptional:!1}}});export{o as KBSnapshotModel,i as RuleModel,a as RuleVersionModel,n as SourceDocumentModel,r as SourceRefModel};

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:`kb.source.ingested`,version:1,description:`Source document ingested (immutable).`,payload:t({name:`KbSourceIngestedPayload`,description:`Emitted when a source document is ingested.`,fields:{sourceDocumentId:{type:n.String_unsecure(),isOptional:!1},jurisdiction:{type:n.String_unsecure(),isOptional:!1},hash:{type:n.String_unsecure(),isOptional:!1}}})}),i=e({name:`kb.ruleVersion.created`,version:1,description:`Rule version created (draft).`,payload:t({name:`KbRuleVersionCreatedPayload`,description:`Emitted when a rule version draft is created.`,fields:{ruleVersionId:{type:n.String_unsecure(),isOptional:!1},ruleId:{type:n.String_unsecure(),isOptional:!1},jurisdiction:{type:n.String_unsecure(),isOptional:!1},status:{type:n.String_unsecure(),isOptional:!1}}})}),a=e({name:`kb.ruleVersion.approved`,version:1,description:`Rule version approved (human verified).`,payload:t({name:`KbRuleVersionApprovedPayload`,description:`Emitted when a rule version is approved.`,fields:{ruleVersionId:{type:n.String_unsecure(),isOptional:!1},approver:{type:n.String_unsecure(),isOptional:!1}}})}),o=e({name:`kb.snapshot.published`,version:1,description:`KB snapshot published.`,payload:t({name:`KbSnapshotPublishedPayload`,description:`Emitted when a KB snapshot is published.`,fields:{snapshotId:{type:n.String_unsecure(),isOptional:!1},jurisdiction:{type:n.String_unsecure(),isOptional:!1},includedRuleVersionsCount:{type:n.Int_unsecure(),isOptional:!1}}})});export{a as KbRuleVersionApprovedEvent,i as KbRuleVersionCreatedEvent,o as KbSnapshotPublishedEvent,r as KbSourceIngestedEvent};

package/dist/example.js

@@ -0,0 +1 @@
+var e={id:`versioned-knowledge-base`,title:`Versioned Knowledge Base`,summary:`Curated KB with immutable sources, reviewable rule versions, and published snapshots.`,tags:[`knowledge`,`versioning`,`snapshots`],kind:`knowledge`,visibility:`public`,docs:{rootDocId:`docs.examples.versioned-knowledge-base`},entrypoints:{packageName:`@lssm/example.versioned-knowledge-base`,feature:`./feature`,contracts:`./contracts`,handlers:`./handlers`,docs:`./docs`},surfaces:{templates:!0,sandbox:{enabled:!0,modes:[`markdown`,`specs`,`builder`]},studio:{enabled:!0,installable:!0},mcp:{enabled:!0}}};export{e as default};

package/dist/feature.js

@@ -0,0 +1 @@
+const e={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}]}};export{e as VersionedKnowledgeBaseFeature};

package/dist/handlers/index.js

@@ -0,0 +1 @@
+import{createMemoryKbHandlers as e,createMemoryKbStore as t}from"./memory.handlers.js";export{e as createMemoryKbHandlers,t as createMemoryKbStore};

package/dist/handlers/memory.handlers.js

@@ -0,0 +1 @@
+function e(){return{sources:new Map,rules:new Map,ruleVersions:new Map,snapshots:new Map,nextRuleVersionNumberByRuleId:new Map}}function t(e,t){return`${e}_${t.replace(/[^a-zA-Z0-9_-]/g,`_`)}`}function n(e){async function n(t){return e.rules.set(t.id,t),t}async function r(n){let r=t(`src`,`${n.jurisdiction}_${n.hash}`),i={id:r,...n};return e.sources.set(r,i),i}async function i(n){if(!n.sourceRefs.length)throw Error(`SOURCE_REFS_REQUIRED`);let r=e.rules.get(n.ruleId);if(!r)throw Error(`RULE_NOT_FOUND`);let i=(e.nextRuleVersionNumberByRuleId.get(n.ruleId)??0)+1;e.nextRuleVersionNumberByRuleId.set(n.ruleId,i);let a=t(`rv`,`${n.ruleId}_${i}`),o={id:a,ruleId:n.ruleId,jurisdiction:r.jurisdiction,topicKey:r.topicKey,version:i,content:n.content,sourceRefs:n.sourceRefs,status:`draft`,createdAt:new Date,approvedAt:void 0,approvedBy:void 0};return e.ruleVersions.set(a,o),o}async function a(t){let n=e.ruleVersions.get(t.ruleVersionId);if(!n)throw Error(`RULE_VERSION_NOT_FOUND`);let r={...n,status:`approved`,approvedBy:t.approver,approvedAt:new Date};return e.ruleVersions.set(r.id,r),r}async function o(n){let r=[...e.ruleVersions.values()].filter(e=>e.status===`approved`&&e.jurisdiction===n.jurisdiction);if(r.length===0)throw Error(`NO_APPROVED_RULES`);let i=r.map(e=>e.id).sort(),a=t(`snap`,`${n.jurisdiction}_${n.asOfDate.toISOString().slice(0,10)}_${i.length}`),o={id:a,jurisdiction:n.jurisdiction,asOfDate:n.asOfDate,includedRuleVersionIds:i,publishedAt:new Date};return e.snapshots.set(a,o),o}async function s(t){let n=e.snapshots.get(t.snapshotId);if(!n)throw Error(`SNAPSHOT_NOT_FOUND`);if(n.jurisdiction!==t.jurisdiction)throw Error(`JURISDICTION_MISMATCH`);let r=t.query.toLowerCase().split(/\s+/).map(e=>e.trim()).filter(Boolean);return{items:n.includedRuleVersionIds.map(t=>e.ruleVersions.get(t)).filter(e=>!!e).filter(e=>{if(r.length===0)return!0;let t=e.content.toLowerCase();return r.every(e=>t.includes(e))}).map(e=>({ruleVersionId:e.id,excerpt:e.content.slice(0,120)}))}}return{createRule:n,ingestSource:r,upsertRuleVersion:i,approveRuleVersion:a,publishSnapshot:o,search:s}}export{n as createMemoryKbHandlers,e as createMemoryKbStore};

package/dist/index.js

@@ -0,0 +1 @@
+import{KbRuleVersionApprovedEvent as e,KbRuleVersionCreatedEvent as t,KbSnapshotPublishedEvent as n,KbSourceIngestedEvent as r}from"./events.js";import i from"./example.js";import{VersionedKnowledgeBaseFeature as a}from"./feature.js";import{KBSnapshotModel as o,RuleModel as s,RuleVersionModel as c,SourceDocumentModel as l,SourceRefModel as u}from"./entities/models.js";import"./entities/index.js";import{KbApproveRuleVersionContract as d,KbIngestSourceContract as f,KbPublishSnapshotContract as p,KbSearchContract as m,KbUpsertRuleVersionContract as h}from"./contracts/kb.js";import"./contracts/index.js";import{createMemoryKbHandlers as g,createMemoryKbStore as _}from"./handlers/memory.handlers.js";import"./docs/index.js";export{o as KBSnapshotModel,d as KbApproveRuleVersionContract,f as KbIngestSourceContract,p as KbPublishSnapshotContract,e as KbRuleVersionApprovedEvent,t as KbRuleVersionCreatedEvent,m as KbSearchContract,n as KbSnapshotPublishedEvent,r as KbSourceIngestedEvent,h as KbUpsertRuleVersionContract,s as RuleModel,c as RuleVersionModel,l as SourceDocumentModel,u as SourceRefModel,a as VersionedKnowledgeBaseFeature,g as createMemoryKbHandlers,_ as createMemoryKbStore,i as example};

package/example.ts

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@lssm/example.versioned-knowledge-base",
+  "version": "0.0.0-canary-20251213172311",
+  "description": "Example: curated, versioned knowledge base with immutable sources, rule versions, and published snapshots.",
+  "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/kb": "./src/contracts/kb.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/versioned-knowledge-base.docblock": "./src/docs/versioned-knowledge-base.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/memory.handlers": "./src/handlers/memory.handlers.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/kb": "./dist/contracts/kb.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/versioned-knowledge-base.docblock": "./dist/docs/versioned-knowledge-base.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/memory.handlers": "./dist/handlers/memory.handlers.js",
+      "./*": "./*"
+    }
+  }
+}

package/src/contracts/index.ts

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

package/src/contracts/kb.ts

@@ -0,0 +1,191 @@
+import { defineCommand, defineQuery } from '@lssm/lib.contracts';
+import { ScalarTypeEnum, defineSchemaModel } from '@lssm/lib.schema';
+
+import {
+  KBSnapshotModel,
+  RuleVersionModel,
+  SourceDocumentModel,
+  SourceRefModel,
+} from '../entities/models';
+
+const IngestSourceInput = defineSchemaModel({
+  name: 'KbIngestSourceInput',
+  description: 'Ingest immutable source metadata referencing a stored file.',
+  fields: {
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    authority: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    fetchedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    hash: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    fileId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+const UpsertRuleVersionInput = defineSchemaModel({
+  name: 'KbUpsertRuleVersionInput',
+  description: 'Create a new draft rule version (immutable history).',
+  fields: {
+    ruleId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    sourceRefs: { type: SourceRefModel, isArray: true, isOptional: false },
+  },
+});
+
+const ApproveRuleVersionInput = defineSchemaModel({
+  name: 'KbApproveRuleVersionInput',
+  description: 'Approve a rule version (human verification).',
+  fields: {
+    ruleVersionId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    approver: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+const PublishSnapshotInput = defineSchemaModel({
+  name: 'KbPublishSnapshotInput',
+  description: 'Publish a snapshot for a jurisdiction as-of a date.',
+  fields: {
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    asOfDate: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+const SearchKbInput = defineSchemaModel({
+  name: 'KbSearchInput',
+  description: 'Search within a published snapshot.',
+  fields: {
+    snapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    query: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+const SearchKbResultItem = defineSchemaModel({
+  name: 'KbSearchResultItem',
+  description: 'Search result referencing a specific rule version.',
+  fields: {
+    ruleVersionId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    excerpt: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+  },
+});
+
+const SearchKbOutput = defineSchemaModel({
+  name: 'KbSearchOutput',
+  description: 'Search results constrained to snapshot + jurisdiction.',
+  fields: {
+    items: { type: SearchKbResultItem, isArray: true, isOptional: false },
+  },
+});
+
+export const KbIngestSourceContract = defineCommand({
+  meta: {
+    name: 'kb.ingestSource',
+    version: 1,
+    stability: 'experimental',
+    owners: ['examples'],
+    tags: ['knowledge', 'sources', 'ingestion'],
+    description: 'Ingest immutable source document metadata.',
+    goal: 'Store traceable source documents for curated KB.',
+    context: 'Called when an admin uploads/records authoritative sources.',
+  },
+  io: {
+    input: IngestSourceInput,
+    output: SourceDocumentModel,
+  },
+  policy: { auth: 'user' },
+});
+
+export const KbUpsertRuleVersionContract = defineCommand({
+  meta: {
+    name: 'kb.upsertRuleVersion',
+    version: 1,
+    stability: 'experimental',
+    owners: ['examples'],
+    tags: ['knowledge', 'rules', 'versioning'],
+    description: 'Create a new draft rule version with source references.',
+    goal: 'Propose curated knowledge updates with traceability.',
+    context: 'Automation or curators propose draft rule versions.',
+  },
+  io: {
+    input: UpsertRuleVersionInput,
+    output: RuleVersionModel,
+    errors: {
+      SOURCE_REFS_REQUIRED: {
+        description: 'Rule version must cite at least one sourceRef',
+        http: 400,
+        gqlCode: 'SOURCE_REFS_REQUIRED',
+        when: 'sourceRefs is empty',
+      },
+      RULE_NOT_FOUND: {
+        description: 'Rule does not exist',
+        http: 404,
+        gqlCode: 'RULE_NOT_FOUND',
+        when: 'ruleId is unknown',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+});
+
+export const KbApproveRuleVersionContract = defineCommand({
+  meta: {
+    name: 'kb.approveRuleVersion',
+    version: 1,
+    stability: 'experimental',
+    owners: ['examples'],
+    tags: ['knowledge', 'rules', 'approval'],
+    description: 'Approve a draft rule version.',
+    goal: 'Human verification step before publishing snapshots.',
+    context: 'Curators/experts approve proposed KB changes.',
+  },
+  io: {
+    input: ApproveRuleVersionInput,
+    output: RuleVersionModel,
+  },
+  policy: { auth: 'user' },
+});
+
+export const KbPublishSnapshotContract = defineCommand({
+  meta: {
+    name: 'kb.publishSnapshot',
+    version: 1,
+    stability: 'experimental',
+    owners: ['examples'],
+    tags: ['knowledge', 'snapshots', 'publishing'],
+    description: 'Publish a KB snapshot for a jurisdiction.',
+    goal: 'Create a stable snapshot that assistant answers can cite.',
+    context: 'Publishing happens after approvals; snapshot is referenced by answers.',
+  },
+  io: {
+    input: PublishSnapshotInput,
+    output: KBSnapshotModel,
+    errors: {
+      NO_APPROVED_RULES: {
+        description: 'No approved rule versions available to publish',
+        http: 409,
+        gqlCode: 'NO_APPROVED_RULES',
+        when: 'jurisdiction has zero approved rule versions',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+});
+
+export const KbSearchContract = defineQuery({
+  meta: {
+    name: 'kb.search',
+    version: 1,
+    stability: 'experimental',
+    owners: ['examples'],
+    tags: ['knowledge', 'search', 'snapshots'],
+    description: 'Search within a published KB snapshot.',
+    goal: 'Provide scoped retrieval for assistant answers.',
+    context: 'Assistant queries curated rules from a specific snapshot.',
+  },
+  io: {
+    input: SearchKbInput,
+    output: SearchKbOutput,
+  },
+  policy: { auth: 'user' },
+});
+
+

package/src/docs/index.ts

@@ -0,0 +1,3 @@
+import './versioned-knowledge-base.docblock';
+
+

package/src/docs/versioned-knowledge-base.docblock.ts

@@ -0,0 +1,31 @@
+import type { DocBlock } from '@lssm/lib.contracts/docs';
+import { registerDocBlocks } from '@lssm/lib.contracts/docs';
+
+const docBlocks: DocBlock[] = [
+  {
+    id: 'docs.examples.versioned-knowledge-base.goal',
+    title: 'Versioned Knowledge Base — Goal',
+    summary:
+      'Curated KB with immutable sources, versioned rules, and published snapshots referenced by answers.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/examples/versioned-knowledge-base/goal',
+    tags: ['knowledge', 'versioning', 'snapshots', 'traceability'],
+    body: `## Why it matters
+- Separates raw sources from curated knowledge.\n- Ensures assistant answers cite a published snapshot.\n- Makes change review and safe regeneration possible.\n\n## Core invariants\n- Sources are immutable and content-addressed (hash).\n- Rule versions must cite at least one source.\n- Snapshots include only approved rule versions.`,
+  },
+  {
+    id: 'docs.examples.versioned-knowledge-base.reference',
+    title: 'Versioned Knowledge Base — Reference',
+    summary: 'Entities, contracts, and events for the versioned KB example.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/versioned-knowledge-base',
+    tags: ['knowledge', 'reference'],
+    body: `## Contracts\n- kb.ingestSource\n- kb.upsertRuleVersion\n- kb.approveRuleVersion\n- kb.publishSnapshot\n- kb.search\n\n## Events\n- kb.source.ingested\n- kb.ruleVersion.created\n- kb.ruleVersion.approved\n- kb.snapshot.published`,
+  },
+];
+
+registerDocBlocks(docBlocks);
+
+

package/src/entities/index.ts

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

package/src/entities/models.ts

@@ -0,0 +1,70 @@
+import { ScalarTypeEnum, defineSchemaModel } from '@lssm/lib.schema';
+
+export const SourceDocumentModel = defineSchemaModel({
+  name: 'SourceDocument',
+  description: 'Immutable raw source document metadata referencing a stored file.',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    authority: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    fetchedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    hash: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    fileId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const SourceRefModel = defineSchemaModel({
+  name: 'SourceRef',
+  description: 'Reference to a source document used to justify a rule version.',
+  fields: {
+    sourceDocumentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    excerpt: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+  },
+});
+
+export const RuleModel = defineSchemaModel({
+  name: 'Rule',
+  description: 'Curated rule (stable identity) with topic + jurisdiction scope.',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    topicKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const RuleVersionModel = defineSchemaModel({
+  name: 'RuleVersion',
+  description: 'A versioned rule content with source references and approval status.',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    ruleId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    topicKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    version: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    sourceRefs: { type: SourceRefModel, isArray: true, isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }, // draft|approved|rejected
+    approvedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    approvedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+export const KBSnapshotModel = defineSchemaModel({
+  name: 'KBSnapshot',
+  description: 'Published KB snapshot (as-of) referencing approved rule versions.',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    asOfDate: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    includedRuleVersionIds: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: false,
+    },
+    publishedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+  },
+});
+
+

package/src/events.ts

@@ -0,0 +1,72 @@
+import { defineEvent, defineSchemaModel } from '@lssm/lib.contracts';
+import { ScalarTypeEnum } from '@lssm/lib.schema';
+
+const KbSourceIngestedPayload = defineSchemaModel({
+  name: 'KbSourceIngestedPayload',
+  description: 'Emitted when a source document is ingested.',
+  fields: {
+    sourceDocumentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    hash: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const KbSourceIngestedEvent = defineEvent({
+  name: 'kb.source.ingested',
+  version: 1,
+  description: 'Source document ingested (immutable).',
+  payload: KbSourceIngestedPayload,
+});
+
+const KbRuleVersionCreatedPayload = defineSchemaModel({
+  name: 'KbRuleVersionCreatedPayload',
+  description: 'Emitted when a rule version draft is created.',
+  fields: {
+    ruleVersionId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    ruleId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const KbRuleVersionCreatedEvent = defineEvent({
+  name: 'kb.ruleVersion.created',
+  version: 1,
+  description: 'Rule version created (draft).',
+  payload: KbRuleVersionCreatedPayload,
+});
+
+const KbRuleVersionApprovedPayload = defineSchemaModel({
+  name: 'KbRuleVersionApprovedPayload',
+  description: 'Emitted when a rule version is approved.',
+  fields: {
+    ruleVersionId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    approver: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const KbRuleVersionApprovedEvent = defineEvent({
+  name: 'kb.ruleVersion.approved',
+  version: 1,
+  description: 'Rule version approved (human verified).',
+  payload: KbRuleVersionApprovedPayload,
+});
+
+const KbSnapshotPublishedPayload = defineSchemaModel({
+  name: 'KbSnapshotPublishedPayload',
+  description: 'Emitted when a KB snapshot is published.',
+  fields: {
+    snapshotId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    includedRuleVersionsCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+  },
+});
+
+export const KbSnapshotPublishedEvent = defineEvent({
+  name: 'kb.snapshot.published',
+  version: 1,
+  description: 'KB snapshot published.',
+  payload: KbSnapshotPublishedPayload,
+});
+
+

package/src/example.ts

@@ -0,0 +1,29 @@
+const example = {
+  id: 'versioned-knowledge-base',
+  title: 'Versioned Knowledge Base',
+  summary:
+    'Curated KB with immutable sources, reviewable rule versions, and published snapshots.',
+  tags: ['knowledge', 'versioning', 'snapshots'],
+  kind: 'knowledge',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.versioned-knowledge-base',
+  },
+  entrypoints: {
+    packageName: '@lssm/example.versioned-knowledge-base',
+    feature: './feature',
+    contracts: './contracts',
+    handlers: './handlers',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown', 'specs', 'builder'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+} as const;
+
+export default example;
+
+