@lssm/example.kb-update-pipeline 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/kb-update-pipeline/tsdown.config.js 
+ℹ entry: src/events.ts, src/example.ts, src/feature.ts, src/index.ts, src/contracts/index.ts, src/contracts/pipeline.ts, src/docs/index.ts, src/docs/kb-update-pipeline.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/pipeline.js                3.44 kB │ gzip: 1.18 kB
+ℹ dist/handlers/memory.handlers.js          2.27 kB │ gzip: 0.87 kB
+ℹ dist/events.js                            2.02 kB │ gzip: 0.54 kB
+ℹ dist/index.js                             1.30 kB │ gzip: 0.45 kB
+ℹ dist/docs/kb-update-pipeline.docblock.js  1.26 kB │ gzip: 0.64 kB
+ℹ dist/entities/models.js                   1.11 kB │ gzip: 0.44 kB
+ℹ dist/feature.js                           0.92 kB │ gzip: 0.45 kB
+ℹ dist/example.js                           0.58 kB │ gzip: 0.36 kB
+ℹ dist/contracts/index.js                   0.33 kB │ gzip: 0.16 kB
+ℹ dist/entities/index.js                    0.28 kB │ gzip: 0.16 kB
+ℹ dist/handlers/index.js                    0.17 kB │ gzip: 0.11 kB
+ℹ dist/docs/index.js                        0.04 kB │ gzip: 0.06 kB
+ℹ 12 files, total: 13.72 kB
+✔ Build complete in 53ms
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @lssm/example.kb-update-pipeline
+
+## 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
+  - @lssm/lib.identity-rbac@0.0.0-canary-20251213172311
+  - @lssm/module.notifications@0.0.0-canary-20251213172311

package/README.md

@@ -0,0 +1,18 @@
+# `@lssm/example.kb-update-pipeline`
+
+Spec-first example for a **knowledge base update pipeline** where:
+
+- automation **proposes** changes (watch/diff/summarize/propose patches)\n+- humans **verify** (HITL) with role-based rules\n+- snapshots are published only when rule versions are approved\n+- notifications + audit trails provide traceability\n+
+## Contracts
+
+- `kbPipeline.runWatch()`\n+- `kbPipeline.createReviewTask(changeCandidateId)`\n+- `kbPipeline.submitDecision(reviewTaskId, decision)`\n+- `kbPipeline.publishIfReady(jurisdiction)`\n+
+## Tests
+
+- high-risk change cannot be approved by curator role\n+- publish fails if any included rule versions are unapproved\n+- notifications fire on review requested\n+
+## Running tests
+
+```bash
+bun test
+```
+
+

package/dist/contracts/index.js

@@ -0,0 +1 @@
+import{KbPipelineCreateReviewTaskContract as e,KbPipelinePublishIfReadyContract as t,KbPipelineRunWatchContract as n,KbPipelineSubmitDecisionContract as r}from"./pipeline.js";export{e as KbPipelineCreateReviewTaskContract,t as KbPipelinePublishIfReadyContract,n as KbPipelineRunWatchContract,r as KbPipelineSubmitDecisionContract};

package/dist/contracts/pipeline.js

@@ -0,0 +1 @@
+import{ChangeCandidateModel as e,ReviewDecisionEnum as t,ReviewTaskModel as n}from"../entities/models.js";import{defineCommand as r}from"@lssm/lib.contracts";import{ScalarTypeEnum as i,defineSchemaModel as a}from"@lssm/lib.schema";const o=a({name:`KbPipelineRunWatchInput`,description:`Trigger a watch cycle for KB sources (demo).`,fields:{jurisdiction:{type:i.String_unsecure(),isOptional:!1}}}),s=a({name:`KbPipelineRunWatchOutput`,description:`Output containing detected changes.`,fields:{candidates:{type:e,isArray:!0,isOptional:!1}}}),c=a({name:`KbPipelineCreateReviewTaskInput`,description:`Create a review task for a change candidate.`,fields:{changeCandidateId:{type:i.String_unsecure(),isOptional:!1}}}),l=a({name:`KbPipelineSubmitDecisionInput`,description:`Submit a decision for a review task.`,fields:{reviewTaskId:{type:i.String_unsecure(),isOptional:!1},decision:{type:t,isOptional:!1},decidedBy:{type:i.String_unsecure(),isOptional:!1},decidedByRole:{type:i.String_unsecure(),isOptional:!1}}}),u=a({name:`KbPipelinePublishIfReadyInput`,description:`Publish snapshot if approvals are satisfied for a jurisdiction.`,fields:{jurisdiction:{type:i.String_unsecure(),isOptional:!1}}}),d=a({name:`KbPipelinePublishIfReadyOutput`,description:`Output for publish-if-ready operation.`,fields:{published:{type:i.Boolean(),isOptional:!1},reason:{type:i.String_unsecure(),isOptional:!0}}}),f=r({meta:{name:`kbPipeline.runWatch`,version:1,stability:`experimental`,owners:[`examples`],tags:[`knowledge`,`pipeline`,`jobs`],description:`Detect source changes and create change candidates.`,goal:`Automate discovery of updates needing review.`,context:`Scheduled job or manual trigger in demos.`},io:{input:o,output:s},policy:{auth:`user`}}),p=r({meta:{name:`kbPipeline.createReviewTask`,version:1,stability:`experimental`,owners:[`examples`],tags:[`knowledge`,`pipeline`,`hitl`],description:`Create a review task for a detected change.`,goal:`Route work to human verifiers.`,context:`Called after change detection or manual selection.`},io:{input:c,output:n},policy:{auth:`user`}}),m=r({meta:{name:`kbPipeline.submitDecision`,version:1,stability:`experimental`,owners:[`examples`],tags:[`knowledge`,`pipeline`,`hitl`,`rbac`],description:`Submit approve/reject decision for a review task.`,goal:`Ensure humans verify before publishing.`,context:`Curator/expert reviews and decides.`},io:{input:l,output:n,errors:{FORBIDDEN_ROLE:{description:`Role not allowed to approve the given risk level`,http:403,gqlCode:`FORBIDDEN_ROLE`,when:`curator attempts to approve a high-risk change`},REVIEW_TASK_NOT_FOUND:{description:`Review task not found`,http:404,gqlCode:`REVIEW_TASK_NOT_FOUND`,when:`reviewTaskId is invalid`}}},policy:{auth:`user`}}),h=r({meta:{name:`kbPipeline.publishIfReady`,version:1,stability:`experimental`,owners:[`examples`],tags:[`knowledge`,`pipeline`,`publishing`],description:`Publish snapshot if ready (all approvals satisfied).`,goal:`Prevent publishing until all required approvals exist.`,context:`Called by job or UI to attempt publish.`},io:{input:u,output:d,errors:{NOT_READY:{description:`Publishing is blocked because approvals are incomplete`,http:409,gqlCode:`NOT_READY`,when:`there are open review tasks or unapproved rule versions`}}},policy:{auth:`user`}});export{p as KbPipelineCreateReviewTaskContract,h as KbPipelinePublishIfReadyContract,f as KbPipelineRunWatchContract,m as KbPipelineSubmitDecisionContract};

package/dist/docs/index.js

@@ -0,0 +1 @@
+import"./kb-update-pipeline.docblock.js";

package/dist/docs/kb-update-pipeline.docblock.js

@@ -0,0 +1,19 @@
+import{registerDocBlocks as e}from"@lssm/lib.contracts/docs";e([{id:`docs.examples.kb-update-pipeline.goal`,title:`KB Update Pipeline — Goal`,summary:`Automation proposes KB patches; humans verify; publishing is blocked until approvals are complete.`,kind:`goal`,visibility:`public`,route:`/docs/examples/kb-update-pipeline/goal`,tags:[`knowledge`,`pipeline`,`hitl`,`audit`],body:`## Why it matters
+- Keeps humans as the verifiers (HITL) while automation does the busywork.
+- Produces an auditable chain: source change -> diff -> proposal -> review -> publish.
+
+## Guardrails
+- High-risk changes require expert approval.
+- Publishing fails if any included rule versions are not approved.
+- Review requests emit notifications/events.`},{id:`docs.examples.kb-update-pipeline.reference`,title:`KB Update Pipeline — Reference`,summary:`Entities, contracts, and events for the KB update pipeline example.`,kind:`reference`,visibility:`public`,route:`/docs/examples/kb-update-pipeline`,tags:[`knowledge`,`reference`],body:`## Contracts
+- kbPipeline.runWatch
+- kbPipeline.createReviewTask
+- kbPipeline.submitDecision
+- kbPipeline.publishIfReady
+
+## Events
+- kb.change.detected
+- kb.change.summarized
+- kb.patch.proposed
+- kb.review.requested
+- kb.review.decided`}]);

package/dist/entities/index.js

@@ -0,0 +1 @@
+import{ChangeCandidateModel as e,ChangeRiskLevelEnum as t,ReviewAssignedRoleEnum as n,ReviewDecisionEnum as r,ReviewTaskModel as i}from"./models.js";export{e as ChangeCandidateModel,t as ChangeRiskLevelEnum,n as ReviewAssignedRoleEnum,r as ReviewDecisionEnum,i as ReviewTaskModel};

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(`ChangeRiskLevel`,[`low`,`medium`,`high`]),i=t(`ReviewAssignedRole`,[`curator`,`expert`]),a=t(`ReviewDecision`,[`approve`,`reject`]),o=n({name:`ChangeCandidate`,description:`Candidate change detected in a source document.`,fields:{id:{type:e.String_unsecure(),isOptional:!1},sourceDocumentId:{type:e.String_unsecure(),isOptional:!1},detectedAt:{type:e.DateTime(),isOptional:!1},diffSummary:{type:e.String_unsecure(),isOptional:!1},riskLevel:{type:r,isOptional:!1}}}),s=n({name:`ReviewTask`,description:`Human verification task for a change candidate.`,fields:{id:{type:e.String_unsecure(),isOptional:!1},changeCandidateId:{type:e.String_unsecure(),isOptional:!1},status:{type:e.String_unsecure(),isOptional:!1},assignedRole:{type:i,isOptional:!1},decision:{type:a,isOptional:!0},decidedAt:{type:e.DateTime(),isOptional:!0},decidedBy:{type:e.String_unsecure(),isOptional:!0}}});export{o as ChangeCandidateModel,r as ChangeRiskLevelEnum,i as ReviewAssignedRoleEnum,a as ReviewDecisionEnum,s as ReviewTaskModel};

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.change.detected`,version:1,description:`KB source change detected.`,payload:t({name:`KbChangeDetectedPayload`,description:`Emitted when a source change is detected.`,fields:{changeCandidateId:{type:n.String_unsecure(),isOptional:!1},sourceDocumentId:{type:n.String_unsecure(),isOptional:!1},riskLevel:{type:n.String_unsecure(),isOptional:!1}}})}),i=e({name:`kb.change.summarized`,version:1,description:`KB change summarized.`,payload:t({name:`KbChangeSummarizedPayload`,description:`Emitted when a change summary is produced.`,fields:{changeCandidateId:{type:n.String_unsecure(),isOptional:!1},summary:{type:n.String_unsecure(),isOptional:!1},riskLevel:{type:n.String_unsecure(),isOptional:!1}}})}),a=e({name:`kb.patch.proposed`,version:1,description:`KB rule patch proposed (draft versions created).`,payload:t({name:`KbPatchProposedPayload`,description:`Emitted when draft rule patches are proposed.`,fields:{changeCandidateId:{type:n.String_unsecure(),isOptional:!1},proposedRuleVersionIds:{type:n.String_unsecure(),isArray:!0,isOptional:!1}}})}),o=e({name:`kb.review.requested`,version:1,description:`KB review requested.`,payload:t({name:`KbReviewRequestedPayload`,description:`Emitted when a review is requested.`,fields:{reviewTaskId:{type:n.String_unsecure(),isOptional:!1},changeCandidateId:{type:n.String_unsecure(),isOptional:!1},assignedRole:{type:n.String_unsecure(),isOptional:!1}}})}),s=e({name:`kb.review.decided`,version:1,description:`KB review decided.`,payload:t({name:`KbReviewDecidedPayload`,description:`Emitted when a review task is decided.`,fields:{reviewTaskId:{type:n.String_unsecure(),isOptional:!1},decision:{type:n.String_unsecure(),isOptional:!1},decidedBy:{type:n.String_unsecure(),isOptional:!1}}})});export{r as KbChangeDetectedEvent,i as KbChangeSummarizedEvent,a as KbPatchProposedEvent,s as KbReviewDecidedEvent,o as KbReviewRequestedEvent};

package/dist/example.js

@@ -0,0 +1 @@
+var e={id:`kb-update-pipeline`,title:`KB Update Pipeline`,summary:`Automation proposes KB updates; humans verify; everything audited and notified.`,tags:[`knowledge`,`pipeline`,`hitl`,`audit`],kind:`knowledge`,visibility:`public`,docs:{rootDocId:`docs.examples.kb-update-pipeline`},entrypoints:{packageName:`@lssm/example.kb-update-pipeline`,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:`kb-update-pipeline`,title:`KB Update Pipeline (HITL)`,description:`Automation proposes KB patches; humans verify; publishing is blocked until approvals are complete.`,domain:`knowledge`,owners:[`examples`],tags:[`knowledge`,`pipeline`,`hitl`,`audit`,`notifications`],stability:`experimental`},operations:[{name:`kbPipeline.runWatch`,version:1},{name:`kbPipeline.createReviewTask`,version:1},{name:`kbPipeline.submitDecision`,version:1},{name:`kbPipeline.publishIfReady`,version:1}],events:[{name:`kb.change.detected`,version:1},{name:`kb.change.summarized`,version:1},{name:`kb.patch.proposed`,version:1},{name:`kb.review.requested`,version:1},{name:`kb.review.decided`,version:1}],presentations:[],opToPresentation:[],presentationsTargets:[],capabilities:{requires:[{key:`identity`,version:1},{key:`notifications`,version:1},{key:`audit-trail`,version:1}]}};export{e as KbUpdatePipelineFeature};

package/dist/handlers/index.js

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

package/dist/handlers/memory.handlers.js

@@ -0,0 +1 @@
+function e(){return{candidates:new Map,reviewTasks:new Map,proposedRuleVersionIdsByCandidate:new Map,approvedRuleVersionIds:new Set,notifications:[]}}function t(e,t){return`${e}_${t.replace(/[^a-zA-Z0-9_-]/g,`_`)}`}function n(e){async function n(t){return{candidates:[...e.candidates.values()].filter(e=>e.sourceDocumentId.startsWith(`${t.jurisdiction}_`)||!0)}}async function r(n){let r=e.candidates.get(n.changeCandidateId);if(!r)throw Error(`CHANGE_CANDIDATE_NOT_FOUND`);let i=r.riskLevel===`high`?`expert`:`curator`,a=t(`review`,n.changeCandidateId),o={id:a,changeCandidateId:n.changeCandidateId,status:`open`,assignedRole:i,decision:void 0,decidedAt:void 0,decidedBy:void 0};return e.reviewTasks.set(a,o),e.notifications.push({kind:`kb.review.requested`,reviewTaskId:a,changeCandidateId:n.changeCandidateId,assignedRole:i,createdAt:new Date}),o}async function i(t){if(!e.candidates.has(t.changeCandidateId))throw Error(`CHANGE_CANDIDATE_NOT_FOUND`);return e.proposedRuleVersionIdsByCandidate.set(t.changeCandidateId,[...t.proposedRuleVersionIds]),{proposedRuleVersionIds:[...t.proposedRuleVersionIds]}}async function a(t){return e.approvedRuleVersionIds.add(t.ruleVersionId),{ruleVersionId:t.ruleVersionId}}async function o(t){let n=e.reviewTasks.get(t.reviewTaskId);if(!n)throw Error(`REVIEW_TASK_NOT_FOUND`);let r=e.candidates.get(n.changeCandidateId);if(!r)throw Error(`CHANGE_CANDIDATE_NOT_FOUND`);if(r.riskLevel===`high`&&t.decision===`approve`&&t.decidedByRole!==`expert`)throw Error(`FORBIDDEN_ROLE`);let i={...n,status:`decided`,decision:t.decision,decidedAt:new Date,decidedBy:t.decidedBy};return e.reviewTasks.set(i.id,i),i}async function s(t){if([...e.reviewTasks.values()].filter(e=>e.status!==`decided`).length)throw Error(`NOT_READY`);if([...e.reviewTasks.values()].some(e=>e.decision===`reject`))return{published:!1,reason:`REJECTED`};for(let t of e.reviewTasks.values())if(t.decision===`approve`&&(e.proposedRuleVersionIdsByCandidate.get(t.changeCandidateId)??[]).filter(t=>!e.approvedRuleVersionIds.has(t)).length)throw Error(`NOT_READY`);return{published:!0}}return{runWatch:n,createReviewTask:r,proposeRulePatch:i,markRuleVersionApproved:a,submitDecision:o,publishIfReady:s}}export{n as createPipelineMemoryHandlers,e as createPipelineMemoryStore};

package/dist/index.js

@@ -0,0 +1 @@
+import{KbChangeDetectedEvent as e,KbChangeSummarizedEvent as t,KbPatchProposedEvent as n,KbReviewDecidedEvent as r,KbReviewRequestedEvent as i}from"./events.js";import a from"./example.js";import{KbUpdatePipelineFeature as o}from"./feature.js";import{ChangeCandidateModel as s,ChangeRiskLevelEnum as c,ReviewAssignedRoleEnum as l,ReviewDecisionEnum as u,ReviewTaskModel as d}from"./entities/models.js";import"./entities/index.js";import{KbPipelineCreateReviewTaskContract as f,KbPipelinePublishIfReadyContract as p,KbPipelineRunWatchContract as m,KbPipelineSubmitDecisionContract as h}from"./contracts/pipeline.js";import"./contracts/index.js";import{createPipelineMemoryHandlers as g,createPipelineMemoryStore as _}from"./handlers/memory.handlers.js";import"./docs/index.js";export{s as ChangeCandidateModel,c as ChangeRiskLevelEnum,e as KbChangeDetectedEvent,t as KbChangeSummarizedEvent,n as KbPatchProposedEvent,f as KbPipelineCreateReviewTaskContract,p as KbPipelinePublishIfReadyContract,m as KbPipelineRunWatchContract,h as KbPipelineSubmitDecisionContract,r as KbReviewDecidedEvent,i as KbReviewRequestedEvent,o as KbUpdatePipelineFeature,l as ReviewAssignedRoleEnum,u as ReviewDecisionEnum,d as ReviewTaskModel,g as createPipelineMemoryHandlers,_ as createPipelineMemoryStore,a as example};

package/example.ts

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

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@lssm/example.kb-update-pipeline",
+  "version": "0.0.0-canary-20251213172311",
+  "description": "Example: KB update automation pipeline with HITL review and auditability.",
+  "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/pipeline": "./src/contracts/pipeline.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/kb-update-pipeline.docblock": "./src/docs/kb-update-pipeline.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.identity-rbac": "workspace:*",
+    "@lssm/lib.schema": "workspace:*",
+    "@lssm/module.notifications": "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/pipeline": "./dist/contracts/pipeline.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/kb-update-pipeline.docblock": "./dist/docs/kb-update-pipeline.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 './pipeline';
+
+

package/src/contracts/pipeline.ts

@@ -0,0 +1,146 @@
+import { defineCommand } from '@lssm/lib.contracts';
+import { ScalarTypeEnum, defineSchemaModel } from '@lssm/lib.schema';
+
+import { ChangeCandidateModel, ReviewDecisionEnum, ReviewTaskModel } from '../entities/models';
+
+const RunWatchInput = defineSchemaModel({
+  name: 'KbPipelineRunWatchInput',
+  description: 'Trigger a watch cycle for KB sources (demo).',
+  fields: {
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+const RunWatchOutput = defineSchemaModel({
+  name: 'KbPipelineRunWatchOutput',
+  description: 'Output containing detected changes.',
+  fields: {
+    candidates: { type: ChangeCandidateModel, isArray: true, isOptional: false },
+  },
+});
+
+const CreateReviewTaskInput = defineSchemaModel({
+  name: 'KbPipelineCreateReviewTaskInput',
+  description: 'Create a review task for a change candidate.',
+  fields: {
+    changeCandidateId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+const SubmitDecisionInput = defineSchemaModel({
+  name: 'KbPipelineSubmitDecisionInput',
+  description: 'Submit a decision for a review task.',
+  fields: {
+    reviewTaskId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    decision: { type: ReviewDecisionEnum, isOptional: false },
+    decidedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    decidedByRole: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+const PublishIfReadyInput = defineSchemaModel({
+  name: 'KbPipelinePublishIfReadyInput',
+  description: 'Publish snapshot if approvals are satisfied for a jurisdiction.',
+  fields: {
+    jurisdiction: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+const PublishIfReadyOutput = defineSchemaModel({
+  name: 'KbPipelinePublishIfReadyOutput',
+  description: 'Output for publish-if-ready operation.',
+  fields: {
+    published: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+  },
+});
+
+export const KbPipelineRunWatchContract = defineCommand({
+  meta: {
+    name: 'kbPipeline.runWatch',
+    version: 1,
+    stability: 'experimental',
+    owners: ['examples'],
+    tags: ['knowledge', 'pipeline', 'jobs'],
+    description: 'Detect source changes and create change candidates.',
+    goal: 'Automate discovery of updates needing review.',
+    context: 'Scheduled job or manual trigger in demos.',
+  },
+  io: { input: RunWatchInput, output: RunWatchOutput },
+  policy: { auth: 'user' },
+});
+
+export const KbPipelineCreateReviewTaskContract = defineCommand({
+  meta: {
+    name: 'kbPipeline.createReviewTask',
+    version: 1,
+    stability: 'experimental',
+    owners: ['examples'],
+    tags: ['knowledge', 'pipeline', 'hitl'],
+    description: 'Create a review task for a detected change.',
+    goal: 'Route work to human verifiers.',
+    context: 'Called after change detection or manual selection.',
+  },
+  io: { input: CreateReviewTaskInput, output: ReviewTaskModel },
+  policy: { auth: 'user' },
+});
+
+export const KbPipelineSubmitDecisionContract = defineCommand({
+  meta: {
+    name: 'kbPipeline.submitDecision',
+    version: 1,
+    stability: 'experimental',
+    owners: ['examples'],
+    tags: ['knowledge', 'pipeline', 'hitl', 'rbac'],
+    description: 'Submit approve/reject decision for a review task.',
+    goal: 'Ensure humans verify before publishing.',
+    context: 'Curator/expert reviews and decides.',
+  },
+  io: {
+    input: SubmitDecisionInput,
+    output: ReviewTaskModel,
+    errors: {
+      FORBIDDEN_ROLE: {
+        description: 'Role not allowed to approve the given risk level',
+        http: 403,
+        gqlCode: 'FORBIDDEN_ROLE',
+        when: 'curator attempts to approve a high-risk change',
+      },
+      REVIEW_TASK_NOT_FOUND: {
+        description: 'Review task not found',
+        http: 404,
+        gqlCode: 'REVIEW_TASK_NOT_FOUND',
+        when: 'reviewTaskId is invalid',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+});
+
+export const KbPipelinePublishIfReadyContract = defineCommand({
+  meta: {
+    name: 'kbPipeline.publishIfReady',
+    version: 1,
+    stability: 'experimental',
+    owners: ['examples'],
+    tags: ['knowledge', 'pipeline', 'publishing'],
+    description: 'Publish snapshot if ready (all approvals satisfied).',
+    goal: 'Prevent publishing until all required approvals exist.',
+    context: 'Called by job or UI to attempt publish.',
+  },
+  io: {
+    input: PublishIfReadyInput,
+    output: PublishIfReadyOutput,
+    errors: {
+      NOT_READY: {
+        description: 'Publishing is blocked because approvals are incomplete',
+        http: 409,
+        gqlCode: 'NOT_READY',
+        when: 'there are open review tasks or unapproved rule versions',
+      },
+    },
+  },
+  policy: { auth: 'user' },
+});
+
+

package/src/docs/index.ts

@@ -0,0 +1,3 @@
+import './kb-update-pipeline.docblock';
+
+

package/src/docs/kb-update-pipeline.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.kb-update-pipeline.goal',
+    title: 'KB Update Pipeline — Goal',
+    summary:
+      'Automation proposes KB patches; humans verify; publishing is blocked until approvals are complete.',
+    kind: 'goal',
+    visibility: 'public',
+    route: '/docs/examples/kb-update-pipeline/goal',
+    tags: ['knowledge', 'pipeline', 'hitl', 'audit'],
+    body: `## Why it matters
+- Keeps humans as the verifiers (HITL) while automation does the busywork.\n- Produces an auditable chain: source change -> diff -> proposal -> review -> publish.\n\n## Guardrails\n- High-risk changes require expert approval.\n- Publishing fails if any included rule versions are not approved.\n- Review requests emit notifications/events.`,
+  },
+  {
+    id: 'docs.examples.kb-update-pipeline.reference',
+    title: 'KB Update Pipeline — Reference',
+    summary: 'Entities, contracts, and events for the KB update pipeline example.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/kb-update-pipeline',
+    tags: ['knowledge', 'reference'],
+    body: `## Contracts\n- kbPipeline.runWatch\n- kbPipeline.createReviewTask\n- kbPipeline.submitDecision\n- kbPipeline.publishIfReady\n\n## Events\n- kb.change.detected\n- kb.change.summarized\n- kb.patch.proposed\n- kb.review.requested\n- kb.review.decided`,
+  },
+];
+
+registerDocBlocks(docBlocks);
+
+

package/src/entities/index.ts

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

package/src/entities/models.ts

@@ -0,0 +1,45 @@
+import { ScalarTypeEnum, defineEnum, defineSchemaModel } from '@lssm/lib.schema';
+
+export const ChangeRiskLevelEnum = defineEnum('ChangeRiskLevel', [
+  'low',
+  'medium',
+  'high',
+]);
+
+export const ReviewAssignedRoleEnum = defineEnum('ReviewAssignedRole', [
+  'curator',
+  'expert',
+]);
+
+export const ReviewDecisionEnum = defineEnum('ReviewDecision', [
+  'approve',
+  'reject',
+]);
+
+export const ChangeCandidateModel = defineSchemaModel({
+  name: 'ChangeCandidate',
+  description: 'Candidate change detected in a source document.',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    sourceDocumentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    detectedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    diffSummary: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    riskLevel: { type: ChangeRiskLevelEnum, isOptional: false },
+  },
+});
+
+export const ReviewTaskModel = defineSchemaModel({
+  name: 'ReviewTask',
+  description: 'Human verification task for a change candidate.',
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    changeCandidateId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }, // open|decided
+    assignedRole: { type: ReviewAssignedRoleEnum, isOptional: false },
+    decision: { type: ReviewDecisionEnum, isOptional: true },
+    decidedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    decidedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+  },
+});
+
+

package/src/events.ts

@@ -0,0 +1,92 @@
+import { defineEvent, defineSchemaModel } from '@lssm/lib.contracts';
+import { ScalarTypeEnum } from '@lssm/lib.schema';
+
+const KbChangeDetectedPayload = defineSchemaModel({
+  name: 'KbChangeDetectedPayload',
+  description: 'Emitted when a source change is detected.',
+  fields: {
+    changeCandidateId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    sourceDocumentId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    riskLevel: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const KbChangeDetectedEvent = defineEvent({
+  name: 'kb.change.detected',
+  version: 1,
+  description: 'KB source change detected.',
+  payload: KbChangeDetectedPayload,
+});
+
+const KbChangeSummarizedPayload = defineSchemaModel({
+  name: 'KbChangeSummarizedPayload',
+  description: 'Emitted when a change summary is produced.',
+  fields: {
+    changeCandidateId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    summary: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    riskLevel: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const KbChangeSummarizedEvent = defineEvent({
+  name: 'kb.change.summarized',
+  version: 1,
+  description: 'KB change summarized.',
+  payload: KbChangeSummarizedPayload,
+});
+
+const KbPatchProposedPayload = defineSchemaModel({
+  name: 'KbPatchProposedPayload',
+  description: 'Emitted when draft rule patches are proposed.',
+  fields: {
+    changeCandidateId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    proposedRuleVersionIds: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: false,
+    },
+  },
+});
+
+export const KbPatchProposedEvent = defineEvent({
+  name: 'kb.patch.proposed',
+  version: 1,
+  description: 'KB rule patch proposed (draft versions created).',
+  payload: KbPatchProposedPayload,
+});
+
+const KbReviewRequestedPayload = defineSchemaModel({
+  name: 'KbReviewRequestedPayload',
+  description: 'Emitted when a review is requested.',
+  fields: {
+    reviewTaskId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    changeCandidateId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    assignedRole: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const KbReviewRequestedEvent = defineEvent({
+  name: 'kb.review.requested',
+  version: 1,
+  description: 'KB review requested.',
+  payload: KbReviewRequestedPayload,
+});
+
+const KbReviewDecidedPayload = defineSchemaModel({
+  name: 'KbReviewDecidedPayload',
+  description: 'Emitted when a review task is decided.',
+  fields: {
+    reviewTaskId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    decision: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    decidedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+  },
+});
+
+export const KbReviewDecidedEvent = defineEvent({
+  name: 'kb.review.decided',
+  version: 1,
+  description: 'KB review decided.',
+  payload: KbReviewDecidedPayload,
+});
+
+

package/src/example.ts

@@ -0,0 +1,29 @@
+const example = {
+  id: 'kb-update-pipeline',
+  title: 'KB Update Pipeline',
+  summary:
+    'Automation proposes KB updates; humans verify; everything audited and notified.',
+  tags: ['knowledge', 'pipeline', 'hitl', 'audit'],
+  kind: 'knowledge',
+  visibility: 'public',
+  docs: {
+    rootDocId: 'docs.examples.kb-update-pipeline',
+  },
+  entrypoints: {
+    packageName: '@lssm/example.kb-update-pipeline',
+    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;
+
+

package/src/feature.ts

@@ -0,0 +1,39 @@
+import type { FeatureModuleSpec } from '@lssm/lib.contracts';
+
+export const KbUpdatePipelineFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'kb-update-pipeline',
+    title: 'KB Update Pipeline (HITL)',
+    description:
+      'Automation proposes KB patches; humans verify; publishing is blocked until approvals are complete.',
+    domain: 'knowledge',
+    owners: ['examples'],
+    tags: ['knowledge', 'pipeline', 'hitl', 'audit', 'notifications'],
+    stability: 'experimental',
+  },
+  operations: [
+    { name: 'kbPipeline.runWatch', version: 1 },
+    { name: 'kbPipeline.createReviewTask', version: 1 },
+    { name: 'kbPipeline.submitDecision', version: 1 },
+    { name: 'kbPipeline.publishIfReady', version: 1 },
+  ],
+  events: [
+    { name: 'kb.change.detected', version: 1 },
+    { name: 'kb.change.summarized', version: 1 },
+    { name: 'kb.patch.proposed', version: 1 },
+    { name: 'kb.review.requested', version: 1 },
+    { name: 'kb.review.decided', version: 1 },
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    requires: [
+      { key: 'identity', version: 1 },
+      { key: 'notifications', version: 1 },
+      { key: 'audit-trail', version: 1 },
+    ],
+  },
+};
+
+

package/src/handlers/index.ts

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