@contractspec/example.kb-update-pipeline 1.44.0

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,
+    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,
+    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,
+    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,
+    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,
+    description: 'KB review decided.',
+    stability: StabilityEnum.Experimental,
+    owners: [],
+    tags: [],
+  },
+  payload: KbReviewDecidedPayload,
+});

package/src/example.ts

@@ -0,0 +1,27 @@
+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: '@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 },
+  },
+} as const;
+
+export default example;

package/src/feature.ts

@@ -0,0 +1,38 @@
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts';
+
+export const KbUpdatePipelineFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'kb-update-pipeline',
+    version: 1,
+    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: [
+    { key: 'kbPipeline.runWatch', version: 1 },
+    { key: 'kbPipeline.createReviewTask', version: 1 },
+    { key: 'kbPipeline.submitDecision', version: 1 },
+    { key: 'kbPipeline.publishIfReady', version: 1 },
+  ],
+  events: [
+    { key: 'kb.change.detected', version: 1 },
+    { key: 'kb.change.summarized', version: 1 },
+    { key: 'kb.patch.proposed', version: 1 },
+    { key: 'kb.review.requested', version: 1 },
+    { key: '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 @@
+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');
+  });
+});

package/src/handlers/memory.handlers.ts

@@ -0,0 +1,186 @@
+interface ChangeCandidate {
+  id: string;
+  sourceDocumentId: string;
+  detectedAt: Date;
+  diffSummary: string;
+  riskLevel: 'low' | 'medium' | 'high';
+}
+
+interface ReviewTask {
+  id: string;
+  changeCandidateId: string;
+  status: 'open' | 'decided';
+  assignedRole: 'curator' | 'expert';
+  decision?: 'approve' | 'reject';
+  decidedAt?: Date;
+  decidedBy?: string;
+}
+
+export interface PipelineMemoryStore {
+  candidates: Map<string, ChangeCandidate>;
+  reviewTasks: Map<string, ReviewTask>;
+  proposedRuleVersionIdsByCandidate: Map<string, string[]>;
+  approvedRuleVersionIds: Set<string>;
+  notifications: {
+    kind: 'kb.review.requested';
+    reviewTaskId: string;
+    changeCandidateId: string;
+    assignedRole: 'curator' | 'expert';
+    createdAt: Date;
+  }[];
+}
+
+export function createPipelineMemoryStore(): PipelineMemoryStore {
+  return {
+    candidates: new Map(),
+    reviewTasks: new Map(),
+    proposedRuleVersionIdsByCandidate: new Map(),
+    approvedRuleVersionIds: new Set(),
+    notifications: [],
+  };
+}
+
+function stableId(prefix: string, value: string): string {
+  return `${prefix}_${value.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+}
+
+export interface PipelineMemoryHandlers {
+  runWatch(input: {
+    jurisdiction: string;
+  }): Promise<{ candidates: ChangeCandidate[] }>;
+  createReviewTask(input: { changeCandidateId: string }): Promise<ReviewTask>;
+  proposeRulePatch(input: {
+    changeCandidateId: string;
+    proposedRuleVersionIds: string[];
+  }): Promise<{ proposedRuleVersionIds: string[] }>;
+  markRuleVersionApproved(input: {
+    ruleVersionId: string;
+  }): Promise<{ ruleVersionId: string }>;
+  submitDecision(input: {
+    reviewTaskId: string;
+    decision: 'approve' | 'reject';
+    decidedBy: string;
+    decidedByRole: 'curator' | 'expert';
+  }): Promise<ReviewTask>;
+  publishIfReady(input: {
+    jurisdiction: string;
+  }): Promise<{ published: boolean; reason?: string }>;
+}
+
+export function createPipelineMemoryHandlers(
+  store: PipelineMemoryStore
+): PipelineMemoryHandlers {
+  async function runWatch(input: { jurisdiction: string }) {
+    // demo: always returns empty unless caller pre-seeds candidates
+    const candidates = [...store.candidates.values()].filter(
+      (c) => c.sourceDocumentId.startsWith(`${input.jurisdiction}_`) || true
+    );
+    return { candidates };
+  }
+
+  async function createReviewTask(input: { changeCandidateId: string }) {
+    const candidate = store.candidates.get(input.changeCandidateId);
+    if (!candidate) throw new Error('CHANGE_CANDIDATE_NOT_FOUND');
+    const assignedRole = candidate.riskLevel === 'high' ? 'expert' : 'curator';
+    const id = stableId('review', input.changeCandidateId);
+    const task: ReviewTask = {
+      id,
+      changeCandidateId: input.changeCandidateId,
+      status: 'open',
+      assignedRole,
+      decision: undefined,
+      decidedAt: undefined,
+      decidedBy: undefined,
+    };
+    store.reviewTasks.set(id, task);
+    store.notifications.push({
+      kind: 'kb.review.requested',
+      reviewTaskId: id,
+      changeCandidateId: input.changeCandidateId,
+      assignedRole,
+      createdAt: new Date(),
+    });
+    return task;
+  }
+
+  async function proposeRulePatch(input: {
+    changeCandidateId: string;
+    proposedRuleVersionIds: string[];
+  }): Promise<{ proposedRuleVersionIds: string[] }> {
+    if (!store.candidates.has(input.changeCandidateId)) {
+      throw new Error('CHANGE_CANDIDATE_NOT_FOUND');
+    }
+    store.proposedRuleVersionIdsByCandidate.set(input.changeCandidateId, [
+      ...input.proposedRuleVersionIds,
+    ]);
+    return { proposedRuleVersionIds: [...input.proposedRuleVersionIds] };
+  }
+
+  async function markRuleVersionApproved(input: {
+    ruleVersionId: string;
+  }): Promise<{ ruleVersionId: string }> {
+    store.approvedRuleVersionIds.add(input.ruleVersionId);
+    return { ruleVersionId: input.ruleVersionId };
+  }
+
+  async function submitDecision(input: {
+    reviewTaskId: string;
+    decision: 'approve' | 'reject';
+    decidedBy: string;
+    decidedByRole: 'curator' | 'expert';
+  }) {
+    const task = store.reviewTasks.get(input.reviewTaskId);
+    if (!task) throw new Error('REVIEW_TASK_NOT_FOUND');
+    const candidate = store.candidates.get(task.changeCandidateId);
+    if (!candidate) throw new Error('CHANGE_CANDIDATE_NOT_FOUND');
+    if (candidate.riskLevel === 'high' && input.decision === 'approve') {
+      if (input.decidedByRole !== 'expert') throw new Error('FORBIDDEN_ROLE');
+    }
+    const decided: ReviewTask = {
+      ...task,
+      status: 'decided',
+      decision: input.decision,
+      decidedAt: new Date(),
+      decidedBy: input.decidedBy,
+    };
+    store.reviewTasks.set(decided.id, decided);
+    return decided;
+  }
+
+  async function publishIfReady(_input: { jurisdiction: string }) {
+    const openTasks = [...store.reviewTasks.values()].filter(
+      (t) => t.status !== 'decided'
+    );
+    if (openTasks.length) {
+      throw new Error('NOT_READY');
+    }
+    const rejected = [...store.reviewTasks.values()].some(
+      (t) => t.decision === 'reject'
+    );
+    if (rejected) return { published: false, reason: 'REJECTED' };
+
+    // Ensure every proposed rule version is approved before publishing.
+    for (const task of store.reviewTasks.values()) {
+      if (task.decision !== 'approve') continue;
+      const proposed =
+        store.proposedRuleVersionIdsByCandidate.get(task.changeCandidateId) ??
+        [];
+      const unapproved = proposed.filter(
+        (id) => !store.approvedRuleVersionIds.has(id)
+      );
+      if (unapproved.length) {
+        throw new Error('NOT_READY');
+      }
+    }
+    return { published: true };
+  }
+
+  return {
+    runWatch,
+    createReviewTask,
+    proposeRulePatch,
+    markRuleVersionApproved,
+    submitDecision,
+    publishIfReady,
+  };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * KB Update Pipeline Example
+ *
+ * Automation proposes KB updates; humans verify; everything audited and notified.
+ */
+export * from './entities';
+export * from './operations';
+export * from './events';
+export * from './handlers';
+export * from './kb-update-pipeline.feature';
+export { default as example } from './example';
+
+export * from './presentations';
+
+import './docs';

package/src/kb-update-pipeline.feature.ts

@@ -0,0 +1,59 @@
+import type { FeatureModuleSpec } from '@contractspec/lib.contracts';
+
+export const KbUpdatePipelineFeature: FeatureModuleSpec = {
+  meta: {
+    key: 'kb-update-pipeline',
+    version: 1,
+    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: [
+    { key: 'kbPipeline.runWatch', version: 1 },
+    { key: 'kbPipeline.createReviewTask', version: 1 },
+    { key: 'kbPipeline.submitDecision', version: 1 },
+    { key: 'kbPipeline.publishIfReady', version: 1 },
+  ],
+  events: [
+    { key: 'kb.change.detected', version: 1 },
+    { key: 'kb.change.summarized', version: 1 },
+    { key: 'kb.patch.proposed', version: 1 },
+    { key: 'kb.review.requested', version: 1 },
+    { key: 'kb.review.decided', version: 1 },
+  ],
+  presentations: [
+    { key: 'kb.dashboard', version: 1 },
+    { key: 'kb.review.list', version: 1 },
+    { key: 'kb.review.form', version: 1 },
+  ],
+  opToPresentation: [
+    {
+      op: { key: 'kbPipeline.runWatch', version: 1 },
+      pres: { key: 'kb.dashboard', version: 1 },
+    },
+    {
+      op: { key: 'kbPipeline.createReviewTask', version: 1 },
+      pres: { key: 'kb.review.list', version: 1 },
+    },
+    {
+      op: { key: 'kbPipeline.submitDecision', version: 1 },
+      pres: { key: 'kb.review.form', version: 1 },
+    },
+  ],
+  presentationsTargets: [
+    { key: 'kb.dashboard', version: 1, targets: ['react', 'markdown'] },
+    { key: 'kb.review.list', version: 1, targets: ['react', 'markdown'] },
+    { key: 'kb.review.form', version: 1, targets: ['react'] },
+  ],
+  capabilities: {
+    requires: [
+      { key: 'identity', version: 1 },
+      { key: 'notifications', version: 1 },
+      { key: 'audit-trail', version: 1 },
+    ],
+  },
+};

package/src/operations/index.ts

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