@contractspec/example.kb-update-pipeline 1.57.0 → 1.59.0

package/dist/browser/operations/index.js

@@ -0,0 +1,199 @@
+// src/entities/models.ts
+import {
+  ScalarTypeEnum,
+  defineEnum,
+  defineSchemaModel
+} from "@contractspec/lib.schema";
+var ChangeRiskLevelEnum = defineEnum("ChangeRiskLevel", [
+  "low",
+  "medium",
+  "high"
+]);
+var ReviewAssignedRoleEnum = defineEnum("ReviewAssignedRole", [
+  "curator",
+  "expert"
+]);
+var ReviewDecisionEnum = defineEnum("ReviewDecision", [
+  "approve",
+  "reject"
+]);
+var 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 }
+  }
+});
+var 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 },
+    assignedRole: { type: ReviewAssignedRoleEnum, isOptional: false },
+    decision: { type: ReviewDecisionEnum, isOptional: true },
+    decidedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    decidedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+
+// src/operations/pipeline.ts
+import { defineCommand } from "@contractspec/lib.contracts";
+import { ScalarTypeEnum as ScalarTypeEnum2, defineSchemaModel as defineSchemaModel2 } from "@contractspec/lib.schema";
+var RunWatchInput = defineSchemaModel2({
+  name: "KbPipelineRunWatchInput",
+  description: "Trigger a watch cycle for KB sources (demo).",
+  fields: {
+    jurisdiction: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false }
+  }
+});
+var RunWatchOutput = defineSchemaModel2({
+  name: "KbPipelineRunWatchOutput",
+  description: "Output containing detected changes.",
+  fields: {
+    candidates: {
+      type: ChangeCandidateModel,
+      isArray: true,
+      isOptional: false
+    }
+  }
+});
+var CreateReviewTaskInput = defineSchemaModel2({
+  name: "KbPipelineCreateReviewTaskInput",
+  description: "Create a review task for a change candidate.",
+  fields: {
+    changeCandidateId: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    }
+  }
+});
+var SubmitDecisionInput = defineSchemaModel2({
+  name: "KbPipelineSubmitDecisionInput",
+  description: "Submit a decision for a review task.",
+  fields: {
+    reviewTaskId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    decision: { type: ReviewDecisionEnum, isOptional: false },
+    decidedBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    decidedByRole: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    }
+  }
+});
+var PublishIfReadyInput = defineSchemaModel2({
+  name: "KbPipelinePublishIfReadyInput",
+  description: "Publish snapshot if approvals are satisfied for a jurisdiction.",
+  fields: {
+    jurisdiction: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false }
+  }
+});
+var PublishIfReadyOutput = defineSchemaModel2({
+  name: "KbPipelinePublishIfReadyOutput",
+  description: "Output for publish-if-ready operation.",
+  fields: {
+    published: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+    reason: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true }
+  }
+});
+var 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" }
+});
+var 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" }
+});
+var 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" }
+});
+var 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" }
+});
+export {
+  KbPipelineSubmitDecisionContract,
+  KbPipelineRunWatchContract,
+  KbPipelinePublishIfReadyContract,
+  KbPipelineCreateReviewTaskContract
+};

package/dist/browser/operations/pipeline.js

@@ -0,0 +1,199 @@
+// src/entities/models.ts
+import {
+  ScalarTypeEnum,
+  defineEnum,
+  defineSchemaModel
+} from "@contractspec/lib.schema";
+var ChangeRiskLevelEnum = defineEnum("ChangeRiskLevel", [
+  "low",
+  "medium",
+  "high"
+]);
+var ReviewAssignedRoleEnum = defineEnum("ReviewAssignedRole", [
+  "curator",
+  "expert"
+]);
+var ReviewDecisionEnum = defineEnum("ReviewDecision", [
+  "approve",
+  "reject"
+]);
+var 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 }
+  }
+});
+var 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 },
+    assignedRole: { type: ReviewAssignedRoleEnum, isOptional: false },
+    decision: { type: ReviewDecisionEnum, isOptional: true },
+    decidedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    decidedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+
+// src/operations/pipeline.ts
+import { defineCommand } from "@contractspec/lib.contracts";
+import { ScalarTypeEnum as ScalarTypeEnum2, defineSchemaModel as defineSchemaModel2 } from "@contractspec/lib.schema";
+var RunWatchInput = defineSchemaModel2({
+  name: "KbPipelineRunWatchInput",
+  description: "Trigger a watch cycle for KB sources (demo).",
+  fields: {
+    jurisdiction: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false }
+  }
+});
+var RunWatchOutput = defineSchemaModel2({
+  name: "KbPipelineRunWatchOutput",
+  description: "Output containing detected changes.",
+  fields: {
+    candidates: {
+      type: ChangeCandidateModel,
+      isArray: true,
+      isOptional: false
+    }
+  }
+});
+var CreateReviewTaskInput = defineSchemaModel2({
+  name: "KbPipelineCreateReviewTaskInput",
+  description: "Create a review task for a change candidate.",
+  fields: {
+    changeCandidateId: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    }
+  }
+});
+var SubmitDecisionInput = defineSchemaModel2({
+  name: "KbPipelineSubmitDecisionInput",
+  description: "Submit a decision for a review task.",
+  fields: {
+    reviewTaskId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    decision: { type: ReviewDecisionEnum, isOptional: false },
+    decidedBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    decidedByRole: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    }
+  }
+});
+var PublishIfReadyInput = defineSchemaModel2({
+  name: "KbPipelinePublishIfReadyInput",
+  description: "Publish snapshot if approvals are satisfied for a jurisdiction.",
+  fields: {
+    jurisdiction: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false }
+  }
+});
+var PublishIfReadyOutput = defineSchemaModel2({
+  name: "KbPipelinePublishIfReadyOutput",
+  description: "Output for publish-if-ready operation.",
+  fields: {
+    published: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+    reason: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true }
+  }
+});
+var 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" }
+});
+var 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" }
+});
+var 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" }
+});
+var 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" }
+});
+export {
+  KbPipelineSubmitDecisionContract,
+  KbPipelineRunWatchContract,
+  KbPipelinePublishIfReadyContract,
+  KbPipelineCreateReviewTaskContract
+};

package/dist/browser/presentations.js

@@ -0,0 +1,120 @@
+// src/entities/models.ts
+import {
+  ScalarTypeEnum,
+  defineEnum,
+  defineSchemaModel
+} from "@contractspec/lib.schema";
+var ChangeRiskLevelEnum = defineEnum("ChangeRiskLevel", [
+  "low",
+  "medium",
+  "high"
+]);
+var ReviewAssignedRoleEnum = defineEnum("ReviewAssignedRole", [
+  "curator",
+  "expert"
+]);
+var ReviewDecisionEnum = defineEnum("ReviewDecision", [
+  "approve",
+  "reject"
+]);
+var 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 }
+  }
+});
+var 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 },
+    assignedRole: { type: ReviewAssignedRoleEnum, isOptional: false },
+    decision: { type: ReviewDecisionEnum, isOptional: true },
+    decidedAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    decidedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+
+// src/presentations.ts
+import { definePresentation, StabilityEnum } from "@contractspec/lib.contracts";
+var 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
+  },
+  targets: ["react", "markdown"]
+});
+var 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"]
+});
+var 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"]
+});
+export {
+  KbReviewListPresentation,
+  KbReviewFormPresentation,
+  KbDashboardPresentation
+};

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

@@ -0,0 +1,85 @@
+// src/tests/operations.test-spec.ts
+import { defineTestSpec } from "@contractspec/lib.contracts";
+var 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" }]
+    }
+  ]
+});
+var 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" }]
+    }
+  ]
+});
+var 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" }]
+    }
+  ]
+});
+export {
+  SubmitDecisionTest,
+  RunWatchTest,
+  CreateReviewTaskTest
+};

package/dist/docs/index.d.ts

@@ -1 +1,2 @@
-export { };
+import './kb-update-pipeline.docblock';
+//# sourceMappingURL=index.d.ts.map

package/dist/docs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,+BAA+B,CAAC"}

package/dist/docs/index.js

@@ -1 +1,44 @@
-import "./kb-update-pipeline.docblock.js";
+// @bun
+// src/docs/kb-update-pipeline.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var docBlocks = [
+  {
+    id: "docs.examples.kb-update-pipeline.goal",
+    title: "KB Update Pipeline \u2014 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 \u2014 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`
+  }
+];
+registerDocBlocks(docBlocks);

package/dist/docs/kb-update-pipeline.docblock.d.ts

@@ -1 +1,2 @@
-export { };
+export {};
+//# sourceMappingURL=kb-update-pipeline.docblock.d.ts.map

package/dist/docs/kb-update-pipeline.docblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-update-pipeline.docblock.d.ts","sourceRoot":"","sources":["../../src/docs/kb-update-pipeline.docblock.ts"],"names":[],"mappings":""}