@contractspec/example.kb-update-pipeline 0.0.0-canary-20260113162409

package/dist/tests/operations.test-spec.js

@@ -0,0 +1,94 @@
+import { defineTestSpec } from "@contractspec/lib.contracts";
+
+//#region src/tests/operations.test-spec.ts
+const RunWatchTest = defineTestSpec({
+	meta: {
+		key: "kbPipeline.runWatch.test",
+		version: "1.0.0",
+		stability: "experimental",
+		owners: ["@example.kb-update-pipeline"],
+		description: "Test for run watch operation",
+		tags: ["test"]
+	},
+	target: {
+		type: "operation",
+		operation: {
+			key: "kbPipeline.runWatch",
+			version: "1.0.0"
+		}
+	},
+	scenarios: [{
+		key: "success",
+		when: { operation: { key: "kbPipeline.runWatch" } },
+		then: [{
+			type: "expectOutput",
+			match: {}
+		}]
+	}, {
+		key: "error",
+		when: { operation: { key: "kbPipeline.runWatch" } },
+		then: [{ type: "expectError" }]
+	}]
+});
+const CreateReviewTaskTest = defineTestSpec({
+	meta: {
+		key: "kbPipeline.createReviewTask.test",
+		version: "1.0.0",
+		stability: "experimental",
+		owners: ["@example.kb-update-pipeline"],
+		description: "Test for creating review task",
+		tags: ["test"]
+	},
+	target: {
+		type: "operation",
+		operation: {
+			key: "kbPipeline.createReviewTask",
+			version: "1.0.0"
+		}
+	},
+	scenarios: [{
+		key: "success",
+		when: { operation: { key: "kbPipeline.createReviewTask" } },
+		then: [{
+			type: "expectOutput",
+			match: {}
+		}]
+	}, {
+		key: "error",
+		when: { operation: { key: "kbPipeline.createReviewTask" } },
+		then: [{ type: "expectError" }]
+	}]
+});
+const SubmitDecisionTest = defineTestSpec({
+	meta: {
+		key: "kbPipeline.submitDecision.test",
+		version: "1.0.0",
+		stability: "experimental",
+		owners: ["@example.kb-update-pipeline"],
+		description: "Test for submitting decision",
+		tags: ["test"]
+	},
+	target: {
+		type: "operation",
+		operation: {
+			key: "kbPipeline.submitDecision",
+			version: "1.0.0"
+		}
+	},
+	scenarios: [{
+		key: "success",
+		when: { operation: { key: "kbPipeline.submitDecision" } },
+		then: [{
+			type: "expectOutput",
+			match: {}
+		}]
+	}, {
+		key: "error",
+		when: { operation: { key: "kbPipeline.submitDecision" } },
+		then: [{ type: "expectError" }]
+	}]
+});
+
+//#endregion
+export { CreateReviewTaskTest, RunWatchTest, SubmitDecisionTest };
+//# sourceMappingURL=operations.test-spec.js.map

package/dist/tests/operations.test-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.test-spec.js","names":[],"sources":["../../src/tests/operations.test-spec.ts"],"sourcesContent":["import { defineTestSpec } from '@contractspec/lib.contracts';\n\nexport const RunWatchTest = defineTestSpec({\n  meta: {\n    key: 'kbPipeline.runWatch.test',\n    version: '1.0.0',\n    stability: 'experimental',\n    owners: ['@example.kb-update-pipeline'],\n    description: 'Test for run watch operation',\n    tags: ['test'],\n  },\n  target: {\n    type: 'operation',\n    operation: { key: 'kbPipeline.runWatch', version: '1.0.0' },\n  },\n  scenarios: [\n    {\n      key: 'success',\n      when: { operation: { key: 'kbPipeline.runWatch' } },\n      then: [{ type: 'expectOutput', match: {} }],\n    },\n    {\n      key: 'error',\n      when: { operation: { key: 'kbPipeline.runWatch' } },\n      then: [{ type: 'expectError' }],\n    },\n  ],\n});\n\nexport const CreateReviewTaskTest = defineTestSpec({\n  meta: {\n    key: 'kbPipeline.createReviewTask.test',\n    version: '1.0.0',\n    stability: 'experimental',\n    owners: ['@example.kb-update-pipeline'],\n    description: 'Test for creating review task',\n    tags: ['test'],\n  },\n  target: {\n    type: 'operation',\n    operation: { key: 'kbPipeline.createReviewTask', version: '1.0.0' },\n  },\n  scenarios: [\n    {\n      key: 'success',\n      when: { operation: { key: 'kbPipeline.createReviewTask' } },\n      then: [{ type: 'expectOutput', match: {} }],\n    },\n    {\n      key: 'error',\n      when: { operation: { key: 'kbPipeline.createReviewTask' } },\n      then: [{ type: 'expectError' }],\n    },\n  ],\n});\n\nexport const SubmitDecisionTest = defineTestSpec({\n  meta: {\n    key: 'kbPipeline.submitDecision.test',\n    version: '1.0.0',\n    stability: 'experimental',\n    owners: ['@example.kb-update-pipeline'],\n    description: 'Test for submitting decision',\n    tags: ['test'],\n  },\n  target: {\n    type: 'operation',\n    operation: { key: 'kbPipeline.submitDecision', version: '1.0.0' },\n  },\n  scenarios: [\n    {\n      key: 'success',\n      when: { operation: { key: 'kbPipeline.submitDecision' } },\n      then: [{ type: 'expectOutput', match: {} }],\n    },\n    {\n      key: 'error',\n      when: { operation: { key: 'kbPipeline.submitDecision' } },\n      then: [{ type: 'expectError' }],\n    },\n  ],\n});\n"],"mappings":";;;AAEA,MAAa,eAAe,eAAe;CACzC,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,8BAA8B;EACvC,aAAa;EACb,MAAM,CAAC,OAAO;EACf;CACD,QAAQ;EACN,MAAM;EACN,WAAW;GAAE,KAAK;GAAuB,SAAS;GAAS;EAC5D;CACD,WAAW,CACT;EACE,KAAK;EACL,MAAM,EAAE,WAAW,EAAE,KAAK,uBAAuB,EAAE;EACnD,MAAM,CAAC;GAAE,MAAM;GAAgB,OAAO,EAAE;GAAE,CAAC;EAC5C,EACD;EACE,KAAK;EACL,MAAM,EAAE,WAAW,EAAE,KAAK,uBAAuB,EAAE;EACnD,MAAM,CAAC,EAAE,MAAM,eAAe,CAAC;EAChC,CACF;CACF,CAAC;AAEF,MAAa,uBAAuB,eAAe;CACjD,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,8BAA8B;EACvC,aAAa;EACb,MAAM,CAAC,OAAO;EACf;CACD,QAAQ;EACN,MAAM;EACN,WAAW;GAAE,KAAK;GAA+B,SAAS;GAAS;EACpE;CACD,WAAW,CACT;EACE,KAAK;EACL,MAAM,EAAE,WAAW,EAAE,KAAK,+BAA+B,EAAE;EAC3D,MAAM,CAAC;GAAE,MAAM;GAAgB,OAAO,EAAE;GAAE,CAAC;EAC5C,EACD;EACE,KAAK;EACL,MAAM,EAAE,WAAW,EAAE,KAAK,+BAA+B,EAAE;EAC3D,MAAM,CAAC,EAAE,MAAM,eAAe,CAAC;EAChC,CACF;CACF,CAAC;AAEF,MAAa,qBAAqB,eAAe;CAC/C,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,8BAA8B;EACvC,aAAa;EACb,MAAM,CAAC,OAAO;EACf;CACD,QAAQ;EACN,MAAM;EACN,WAAW;GAAE,KAAK;GAA6B,SAAS;GAAS;EAClE;CACD,WAAW,CACT;EACE,KAAK;EACL,MAAM,EAAE,WAAW,EAAE,KAAK,6BAA6B,EAAE;EACzD,MAAM,CAAC;GAAE,MAAM;GAAgB,OAAO,EAAE;GAAE,CAAC;EAC5C,EACD;EACE,KAAK;EACL,MAAM,EAAE,WAAW,EAAE,KAAK,6BAA6B,EAAE;EACzD,MAAM,CAAC,EAAE,MAAM,eAAe,CAAC;EAChC,CACF;CACF,CAAC"}

package/example.ts

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

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@contractspec/example.kb-update-pipeline",
+  "version": "0.0.0-canary-20260113162409",
+  "description": "Example: KB update automation pipeline with HITL review and auditability.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.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",
+    "./handlers": "./dist/handlers/index.js",
+    "./handlers/memory.handlers": "./dist/handlers/memory.handlers.js",
+    "./kb-update-pipeline.feature": "./dist/kb-update-pipeline.feature.js",
+    "./operations": "./dist/operations/index.js",
+    "./operations/pipeline": "./dist/operations/pipeline.js",
+    "./presentations": "./dist/presentations.js",
+    "./tests/operations.test-spec": "./dist/tests/operations.test-spec.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "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": {
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113162409",
+    "@contractspec/lib.schema": "0.0.0-canary-20260113162409"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113162409",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113162409",
+    "tsdown": "^0.19.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",
+      "./kb-update-pipeline.feature": "./dist/kb-update-pipeline.feature.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/kb-update-pipeline"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/docs/index.ts

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

package/src/docs/kb-update-pipeline.docblock.ts

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

package/src/entities/models.ts

@@ -0,0 +1,53 @@
+import {
+  ScalarTypeEnum,
+  defineEnum,
+  defineSchemaModel,
+} from '@contractspec/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,134 @@
+import {
+  defineEvent,
+  defineSchemaModel,
+  StabilityEnum,
+} from '@contractspec/lib.contracts';
+import { ScalarTypeEnum } from '@contractspec/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({
+  meta: {
+    key: 'kb.change.detected',
+    version: '1.0.0',
+    description: 'KB source change detected.',
+    stability: StabilityEnum.Experimental,
+    owners: [],
+    tags: [],
+  },
+  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({
+  meta: {
+    key: 'kb.change.summarized',
+    version: '1.0.0',
+    description: 'KB change summarized.',
+    stability: StabilityEnum.Experimental,
+    owners: [],
+    tags: [],
+  },
+  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({
+  meta: {
+    key: 'kb.patch.proposed',
+    version: '1.0.0',
+    description: 'KB rule patch proposed (draft versions created).',
+    stability: StabilityEnum.Experimental,
+    owners: [],
+    tags: [],
+  },
+  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({
+  meta: {
+    key: 'kb.review.requested',
+    version: '1.0.0',
+    description: 'KB review requested.',
+    stability: StabilityEnum.Experimental,
+    owners: [],
+    tags: [],
+  },
+  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({
+  meta: {
+    key: 'kb.review.decided',
+    version: '1.0.0',
+    description: 'KB review decided.',
+    stability: StabilityEnum.Experimental,
+    owners: [],
+    tags: [],
+  },
+  payload: KbReviewDecidedPayload,
+});

package/src/example.ts

@@ -0,0 +1,34 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'kb-update-pipeline',
+    version: '1.0.0',
+    title: 'KB Update Pipeline',
+    description:
+      'Automation proposes KB updates; humans verify; everything audited and notified.',
+    kind: 'knowledge',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['knowledge', 'pipeline', 'hitl', 'audit'],
+  },
+  docs: {
+    rootDocId: 'docs.examples.kb-update-pipeline',
+  },
+  entrypoints: {
+    packageName: '@contractspec/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 },
+  },
+});
+
+export default example;

package/src/handlers/index.ts

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

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

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  createPipelineMemoryHandlers,
+  createPipelineMemoryStore,
+} from './memory.handlers';
+
+describe('@contractspec/example.kb-update-pipeline memory handlers', () => {
+  it('high-risk change cannot be approved by curator role', async () => {
+    const store = createPipelineMemoryStore();
+    const pipeline = createPipelineMemoryHandlers(store);
+
+    store.candidates.set('c1', {
+      id: 'c1',
+      sourceDocumentId: 'EU_src1',
+      detectedAt: new Date(),
+      diffSummary: 'Change detected',
+      riskLevel: 'high',
+    });
+
+    const review = await pipeline.createReviewTask({ changeCandidateId: 'c1' });
+    await expect(
+      pipeline.submitDecision({
+        reviewTaskId: review.id,
+        decision: 'approve',
+        decidedBy: 'u_curator',
+        decidedByRole: 'curator',
+      })
+    ).rejects.toThrow('FORBIDDEN_ROLE');
+  });
+
+  it('fires a notification when review is requested', async () => {
+    const store = createPipelineMemoryStore();
+    const pipeline = createPipelineMemoryHandlers(store);
+
+    store.candidates.set('c2', {
+      id: 'c2',
+      sourceDocumentId: 'EU_src2',
+      detectedAt: new Date(),
+      diffSummary: 'Minor change',
+      riskLevel: 'low',
+    });
+
+    const review = await pipeline.createReviewTask({ changeCandidateId: 'c2' });
+    expect(store.notifications.length).toBe(1);
+    expect(store.notifications[0]?.reviewTaskId).toBe(review.id);
+    expect(store.notifications[0]?.assignedRole).toBe('curator');
+  });
+
+  it('publishing fails if any included rule versions are not approved', async () => {
+    const store = createPipelineMemoryStore();
+    const pipeline = createPipelineMemoryHandlers(store);
+
+    store.candidates.set('c3', {
+      id: 'c3',
+      sourceDocumentId: 'EU_src3',
+      detectedAt: new Date(),
+      diffSummary: 'Change',
+      riskLevel: 'low',
+    });
+
+    const review = await pipeline.createReviewTask({ changeCandidateId: 'c3' });
+    await pipeline.proposeRulePatch({
+      changeCandidateId: 'c3',
+      proposedRuleVersionIds: ['rv1', 'rv2'],
+    });
+    await pipeline.submitDecision({
+      reviewTaskId: review.id,
+      decision: 'approve',
+      decidedBy: 'u_curator',
+      decidedByRole: 'curator',
+    });
+
+    // only approve one of the proposed rule versions
+    await pipeline.markRuleVersionApproved({ ruleVersionId: 'rv1' });
+
+    await expect(
+      pipeline.publishIfReady({ jurisdiction: 'EU' })
+    ).rejects.toThrow('NOT_READY');
+  });
+});