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

package/dist/kb-update-pipeline.feature.js

@@ -1,142 +1,62 @@
+// @bun
+// src/kb-update-pipeline.feature.ts
 import { defineFeature } from "@contractspec/lib.contracts";
-
-//#region src/kb-update-pipeline.feature.ts
-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"
-		}
-	] }
+var 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" }
+    ]
+  }
 });
-
-//#endregion
-export { KbUpdatePipelineFeature };
-//# sourceMappingURL=kb-update-pipeline.feature.js.map
+export {
+  KbUpdatePipelineFeature
+};

package/dist/node/docs/index.js

@@ -0,0 +1,43 @@
+// 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 — 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`
+  }
+];
+registerDocBlocks(docBlocks);

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

@@ -0,0 +1,43 @@
+// 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 — 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`
+  }
+];
+registerDocBlocks(docBlocks);

package/dist/node/entities/index.js

@@ -0,0 +1,56 @@
+// 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 }
+  }
+});
+export {
+  ReviewTaskModel,
+  ReviewDecisionEnum,
+  ReviewAssignedRoleEnum,
+  ChangeRiskLevelEnum,
+  ChangeCandidateModel
+};

package/dist/node/entities/models.js

@@ -0,0 +1,56 @@
+// 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 }
+  }
+});
+export {
+  ReviewTaskModel,
+  ReviewDecisionEnum,
+  ReviewAssignedRoleEnum,
+  ChangeRiskLevelEnum,
+  ChangeCandidateModel
+};

package/dist/node/events.js

@@ -0,0 +1,132 @@
+// src/events.ts
+import {
+  defineEvent,
+  defineSchemaModel,
+  StabilityEnum
+} from "@contractspec/lib.contracts";
+import { ScalarTypeEnum } from "@contractspec/lib.schema";
+var 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 }
+  }
+});
+var KbChangeDetectedEvent = defineEvent({
+  meta: {
+    key: "kb.change.detected",
+    version: "1.0.0",
+    description: "KB source change detected.",
+    stability: StabilityEnum.Experimental,
+    owners: [],
+    tags: []
+  },
+  payload: KbChangeDetectedPayload
+});
+var 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 }
+  }
+});
+var KbChangeSummarizedEvent = defineEvent({
+  meta: {
+    key: "kb.change.summarized",
+    version: "1.0.0",
+    description: "KB change summarized.",
+    stability: StabilityEnum.Experimental,
+    owners: [],
+    tags: []
+  },
+  payload: KbChangeSummarizedPayload
+});
+var 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
+    }
+  }
+});
+var 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
+});
+var 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 }
+  }
+});
+var KbReviewRequestedEvent = defineEvent({
+  meta: {
+    key: "kb.review.requested",
+    version: "1.0.0",
+    description: "KB review requested.",
+    stability: StabilityEnum.Experimental,
+    owners: [],
+    tags: []
+  },
+  payload: KbReviewRequestedPayload
+});
+var 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 }
+  }
+});
+var KbReviewDecidedEvent = defineEvent({
+  meta: {
+    key: "kb.review.decided",
+    version: "1.0.0",
+    description: "KB review decided.",
+    stability: StabilityEnum.Experimental,
+    owners: [],
+    tags: []
+  },
+  payload: KbReviewDecidedPayload
+});
+export {
+  KbReviewRequestedEvent,
+  KbReviewDecidedEvent,
+  KbPatchProposedEvent,
+  KbChangeSummarizedEvent,
+  KbChangeDetectedEvent
+};

package/dist/node/example.js

@@ -0,0 +1,35 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/node/handlers/index.js

@@ -0,0 +1,109 @@
+// src/handlers/memory.handlers.ts
+function createPipelineMemoryStore() {
+  return {
+    candidates: new Map,
+    reviewTasks: new Map,
+    proposedRuleVersionIdsByCandidate: new Map,
+    approvedRuleVersionIds: new Set,
+    notifications: []
+  };
+}
+function stableId(prefix, value) {
+  return `${prefix}_${value.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+}
+function createPipelineMemoryHandlers(store) {
+  async function runWatch(input) {
+    const candidates = [...store.candidates.values()].filter((c) => c.sourceDocumentId.startsWith(`${input.jurisdiction}_`) || true);
+    return { candidates };
+  }
+  async function createReviewTask(input) {
+    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 = {
+      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) {
+    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) {
+    store.approvedRuleVersionIds.add(input.ruleVersionId);
+    return { ruleVersionId: input.ruleVersionId };
+  }
+  async function submitDecision(input) {
+    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 = {
+      ...task,
+      status: "decided",
+      decision: input.decision,
+      decidedAt: new Date,
+      decidedBy: input.decidedBy
+    };
+    store.reviewTasks.set(decided.id, decided);
+    return decided;
+  }
+  async function publishIfReady(_input) {
+    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" };
+    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
+  };
+}
+export {
+  createPipelineMemoryStore,
+  createPipelineMemoryHandlers
+};