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

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

package/src/operations/index.ts

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

package/src/operations/pipeline.ts

@@ -0,0 +1,159 @@
+import { defineCommand } from '@contractspec/lib.contracts';
+import { ScalarTypeEnum, defineSchemaModel } from '@contractspec/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: {
+    key: 'kbPipeline.runWatch',
+    version: '1.0.0',
+    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: {
+    key: 'kbPipeline.createReviewTask',
+    version: '1.0.0',
+    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: {
+    key: 'kbPipeline.submitDecision',
+    version: '1.0.0',
+    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: {
+    key: 'kbPipeline.publishIfReady',
+    version: '1.0.0',
+    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/presentations.ts

@@ -0,0 +1,68 @@
+import { definePresentation, StabilityEnum } from '@contractspec/lib.contracts';
+import { ChangeCandidateModel, ReviewTaskModel } from './entities/models';
+
+export const KbDashboardPresentation = definePresentation({
+  meta: {
+    key: 'kb.dashboard',
+    version: '1.0.0',
+    title: 'KB Update Dashboard',
+    description: 'Overview of KB change candidates and review tasks.',
+    domain: 'knowledge',
+    owners: ['@examples'],
+    tags: ['dashboard', 'knowledge'],
+    stability: StabilityEnum.Experimental,
+    goal: 'Visualize status',
+    context: 'Dashboard',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'KbDashboard',
+    props: ChangeCandidateModel, // Simplified props mapping for example
+  },
+  targets: ['react', 'markdown'],
+});
+
+export const KbReviewListPresentation = definePresentation({
+  meta: {
+    key: 'kb.review.list',
+    version: '1.0.0',
+    title: 'Review Tasks',
+    description: 'List of pending review tasks for the current user.',
+    domain: 'knowledge',
+    owners: ['@examples'],
+    tags: ['list', 'review'],
+    stability: StabilityEnum.Experimental,
+    goal: 'List tasks',
+    context: 'Inbox',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'ReviewTaskList',
+    props: ReviewTaskModel,
+  },
+  targets: ['react', 'markdown'],
+});
+
+export const KbReviewFormPresentation = definePresentation({
+  meta: {
+    key: 'kb.review.form',
+    version: '1.0.0',
+    title: 'Review Change',
+    description: 'Form to approve or reject a KB change candidate.',
+    domain: 'knowledge',
+    owners: ['@examples'],
+    tags: ['form', 'review'],
+    stability: StabilityEnum.Experimental,
+    goal: 'Review',
+    context: 'Detail',
+  },
+  source: {
+    type: 'component',
+    framework: 'react',
+    componentKey: 'ReviewDecisionForm',
+    props: ReviewTaskModel,
+  },
+  targets: ['react'],
+});

package/src/tests/operations.test-spec.ts

@@ -0,0 +1,82 @@
+import { defineTestSpec } from '@contractspec/lib.contracts';
+
+export 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' }],
+    },
+  ],
+});
+
+export 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' }],
+    },
+  ],
+});
+
+export 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' }],
+    },
+  ],
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+
+
+
+
+
+
+
+
+
+