@contractspec/example.workflow-system 1.57.0 → 1.59.0

package/dist/browser/approval/index.js

@@ -0,0 +1,484 @@
+// src/approval/approval.enum.ts
+import { defineEnum } from "@contractspec/lib.schema";
+var ApprovalStatusEnum = defineEnum("ApprovalStatus", [
+  "PENDING",
+  "APPROVED",
+  "REJECTED",
+  "DELEGATED",
+  "ESCALATED",
+  "WITHDRAWN",
+  "EXPIRED"
+]);
+var ApprovalDecisionEnum = defineEnum("ApprovalDecision", [
+  "APPROVE",
+  "REJECT",
+  "REQUEST_CHANGES",
+  "DELEGATE",
+  "ABSTAIN"
+]);
+
+// src/approval/approval.event.ts
+import { defineEvent, defineSchemaModel } from "@contractspec/lib.contracts";
+import { ScalarTypeEnum } from "@contractspec/lib.schema";
+var ApprovalRequestedPayload = defineSchemaModel({
+  name: "ApprovalRequestedEventPayload",
+  description: "Payload when approval is requested",
+  fields: {
+    requestId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    instanceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    workflowKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    approverId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    approverRole: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    dueAt: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var ApprovalDecidedPayload = defineSchemaModel({
+  name: "ApprovalDecidedEventPayload",
+  description: "Payload when approval decision is made",
+  fields: {
+    requestId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    instanceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    decision: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    decidedBy: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    comment: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var ApprovalDelegatedPayload = defineSchemaModel({
+  name: "ApprovalDelegatedEventPayload",
+  description: "Payload when approval is delegated",
+  fields: {
+    requestId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    instanceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    fromUserId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    toUserId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var ApprovalEscalatedPayload = defineSchemaModel({
+  name: "ApprovalEscalatedEventPayload",
+  description: "Payload when approval is escalated",
+  fields: {
+    requestId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    instanceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    escalationLevel: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: false
+    },
+    escalatedTo: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    reason: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var ApprovalRequestedEvent = defineEvent({
+  meta: {
+    key: "workflow.approval.requested",
+    version: "1.0.0",
+    description: "An approval has been requested.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "approval", "requested"]
+  },
+  payload: ApprovalRequestedPayload
+});
+var ApprovalDecidedEvent = defineEvent({
+  meta: {
+    key: "workflow.approval.decided",
+    version: "1.0.0",
+    description: "An approval decision has been made.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "approval", "decided"]
+  },
+  payload: ApprovalDecidedPayload
+});
+var ApprovalDelegatedEvent = defineEvent({
+  meta: {
+    key: "workflow.approval.delegated",
+    version: "1.0.0",
+    description: "An approval has been delegated.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "approval", "delegated"]
+  },
+  payload: ApprovalDelegatedPayload
+});
+var ApprovalEscalatedEvent = defineEvent({
+  meta: {
+    key: "workflow.approval.escalated",
+    version: "1.0.0",
+    description: "An approval has been escalated.",
+    stability: "stable",
+    owners: ["@workflow-team"],
+    tags: ["workflow", "approval", "escalated"]
+  },
+  payload: ApprovalEscalatedPayload
+});
+
+// src/approval/approval.schema.ts
+import { defineSchemaModel as defineSchemaModel2, ScalarTypeEnum as ScalarTypeEnum2 } from "@contractspec/lib.schema";
+var ApprovalRequestModel = defineSchemaModel2({
+  name: "ApprovalRequestModel",
+  description: "An approval request",
+  fields: {
+    id: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    workflowInstanceId: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    },
+    stepExecutionId: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    },
+    approverId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    approverRole: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true
+    },
+    title: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    status: { type: ApprovalStatusEnum, isOptional: false },
+    decision: { type: ApprovalDecisionEnum, isOptional: true },
+    decisionComment: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true
+    },
+    decidedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    dueAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    contextSnapshot: { type: ScalarTypeEnum2.JSON(), isOptional: true },
+    sequenceOrder: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var ApprovalCommentModel = defineSchemaModel2({
+  name: "ApprovalCommentModel",
+  description: "A comment on an approval",
+  fields: {
+    id: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    approvalRequestId: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    },
+    authorId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    content: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    isInternal: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+
+// src/approval/approval.operations.ts
+import {
+  defineCommand,
+  defineQuery
+} from "@contractspec/lib.contracts/operations";
+import { defineSchemaModel as defineSchemaModel3, ScalarTypeEnum as ScalarTypeEnum3 } from "@contractspec/lib.schema";
+var OWNERS = ["@example.workflow-system"];
+var SubmitDecisionContract = defineCommand({
+  meta: {
+    key: "workflow.approval.decide",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["workflow", "approval", "decision"],
+    description: "Submit an approval decision (approve/reject).",
+    goal: "Allow approvers to make decisions on requests.",
+    context: "Approval inbox, workflow detail."
+  },
+  io: {
+    input: defineSchemaModel3({
+      name: "ApproveRejectInput",
+      fields: {
+        requestId: {
+          type: ScalarTypeEnum3.String_unsecure(),
+          isOptional: false
+        },
+        decision: { type: ApprovalDecisionEnum, isOptional: false },
+        comment: { type: ScalarTypeEnum3.String_unsecure(), isOptional: true },
+        data: { type: ScalarTypeEnum3.JSON(), isOptional: true }
+      }
+    }),
+    output: ApprovalRequestModel
+  },
+  policy: { auth: "user" },
+  sideEffects: {
+    emits: [
+      {
+        key: "workflow.approval.decided",
+        version: "1.0.0",
+        when: "Decision is made",
+        payload: ApprovalRequestModel
+      }
+    ],
+    audit: ["workflow.approval.decided"]
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: "approve-request-happy-path",
+        given: ["Approval request is pending", "User is assignee"],
+        when: ["User approves request"],
+        then: ["Request is approved", "ApprovalDecided event is emitted"]
+      }
+    ],
+    examples: [
+      {
+        key: "approve-basic",
+        input: {
+          requestId: "req-123",
+          decision: "approve",
+          comment: "Looks good"
+        },
+        output: { id: "req-123", status: "approved" }
+      }
+    ]
+  }
+});
+var DelegateApprovalContract = defineCommand({
+  meta: {
+    key: "workflow.approval.delegate",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["workflow", "approval", "delegate"],
+    description: "Delegate an approval request to another user.",
+    goal: "Allow approvers to pass approval to others.",
+    context: "Approval inbox."
+  },
+  io: {
+    input: defineSchemaModel3({
+      name: "DelegateInput",
+      fields: {
+        requestId: {
+          type: ScalarTypeEnum3.String_unsecure(),
+          isOptional: false
+        },
+        delegateTo: {
+          type: ScalarTypeEnum3.String_unsecure(),
+          isOptional: false
+        },
+        reason: { type: ScalarTypeEnum3.String_unsecure(), isOptional: true }
+      }
+    }),
+    output: ApprovalRequestModel
+  },
+  policy: { auth: "user" },
+  sideEffects: {
+    emits: [
+      {
+        key: "workflow.approval.delegated",
+        version: "1.0.0",
+        when: "Approval is delegated",
+        payload: ApprovalRequestModel
+      }
+    ],
+    audit: ["workflow.approval.delegated"]
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: "delegate-approval-happy-path",
+        given: ["Approval request is pending", "User is assignee"],
+        when: ["User delegates to another user"],
+        then: ["Assignee is updated", "ApprovalDelegated event is emitted"]
+      }
+    ],
+    examples: [
+      {
+        key: "delegate-to-manager",
+        input: {
+          requestId: "req-123",
+          delegateTo: "user-456",
+          reason: "Out of office"
+        },
+        output: { id: "req-123", assigneeId: "user-456" }
+      }
+    ]
+  }
+});
+var AddApprovalCommentContract = defineCommand({
+  meta: {
+    key: "workflow.approval.comment.add",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["workflow", "approval", "comment"],
+    description: "Add a comment to an approval request.",
+    goal: "Allow discussion on approval requests.",
+    context: "Approval detail view."
+  },
+  io: {
+    input: defineSchemaModel3({
+      name: "AddCommentInput",
+      fields: {
+        requestId: {
+          type: ScalarTypeEnum3.String_unsecure(),
+          isOptional: false
+        },
+        content: { type: ScalarTypeEnum3.NonEmptyString(), isOptional: false },
+        isInternal: { type: ScalarTypeEnum3.Boolean(), isOptional: true }
+      }
+    }),
+    output: ApprovalCommentModel
+  },
+  policy: { auth: "user" },
+  sideEffects: {
+    emits: [
+      {
+        key: "workflow.approval.comment.added",
+        version: "1.0.0",
+        when: "Comment is added",
+        payload: ApprovalCommentModel
+      }
+    ]
+  },
+  acceptance: {
+    scenarios: [
+      {
+        key: "add-comment-happy-path",
+        given: ["Approval request exists"],
+        when: ["User adds a comment"],
+        then: ["Comment is added", "CommentAdded event is emitted"]
+      }
+    ],
+    examples: [
+      {
+        key: "add-question",
+        input: {
+          requestId: "req-123",
+          content: "Can you clarify budget?",
+          isInternal: false
+        },
+        output: { id: "com-789", content: "Can you clarify budget?" }
+      }
+    ]
+  }
+});
+var ListMyApprovalsContract = defineQuery({
+  meta: {
+    key: "workflow.approval.list.mine",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["workflow", "approval", "list", "inbox"],
+    description: "List approval requests assigned to current user.",
+    goal: "Show pending approvals in user inbox.",
+    context: "Approval inbox, dashboard widget."
+  },
+  io: {
+    input: defineSchemaModel3({
+      name: "ListMyApprovalsInput",
+      fields: {
+        status: { type: ApprovalStatusEnum, isOptional: true },
+        limit: {
+          type: ScalarTypeEnum3.Int_unsecure(),
+          isOptional: true,
+          defaultValue: 20
+        },
+        offset: {
+          type: ScalarTypeEnum3.Int_unsecure(),
+          isOptional: true,
+          defaultValue: 0
+        }
+      }
+    }),
+    output: defineSchemaModel3({
+      name: "ListMyApprovalsOutput",
+      fields: {
+        requests: {
+          type: ApprovalRequestModel,
+          isArray: true,
+          isOptional: false
+        },
+        total: { type: ScalarTypeEnum3.Int_unsecure(), isOptional: false },
+        pendingCount: {
+          type: ScalarTypeEnum3.Int_unsecure(),
+          isOptional: false
+        }
+      }
+    })
+  },
+  policy: { auth: "user" },
+  acceptance: {
+    scenarios: [
+      {
+        key: "list-approvals-happy-path",
+        given: ["User has assigned approvals"],
+        when: ["User lists approvals"],
+        then: ["List of requests is returned"]
+      }
+    ],
+    examples: [
+      {
+        key: "list-pending",
+        input: { status: "pending", limit: 10 },
+        output: { requests: [], total: 2, pendingCount: 2 }
+      }
+    ]
+  }
+});
+var GetApprovalContract = defineQuery({
+  meta: {
+    key: "workflow.approval.get",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["workflow", "approval", "get"],
+    description: "Get an approval request with details.",
+    goal: "View approval request details.",
+    context: "Approval detail view."
+  },
+  io: {
+    input: defineSchemaModel3({
+      name: "GetApprovalInput",
+      fields: {
+        requestId: {
+          type: ScalarTypeEnum3.String_unsecure(),
+          isOptional: false
+        }
+      }
+    }),
+    output: ApprovalRequestModel
+  },
+  policy: { auth: "user" },
+  acceptance: {
+    scenarios: [
+      {
+        key: "get-approval-happy-path",
+        given: ["Approval request exists"],
+        when: ["User requests approval details"],
+        then: ["Approval details are returned"]
+      }
+    ],
+    examples: [
+      {
+        key: "get-basic",
+        input: { requestId: "req-123" },
+        output: { id: "req-123", status: "pending" }
+      }
+    ]
+  }
+});
+export {
+  SubmitDecisionContract,
+  ListMyApprovalsContract,
+  GetApprovalContract,
+  DelegateApprovalContract,
+  ApprovalStatusEnum,
+  ApprovalRequestedEvent,
+  ApprovalRequestModel,
+  ApprovalEscalatedEvent,
+  ApprovalDelegatedEvent,
+  ApprovalDecisionEnum,
+  ApprovalDecidedEvent,
+  ApprovalCommentModel,
+  AddApprovalCommentContract
+};

package/dist/browser/docs/index.js

@@ -0,0 +1,103 @@
+// src/docs/workflow-system.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var workflowSystemDocBlocks = [
+  {
+    id: "docs.examples.workflow-system",
+    title: "Workflow / Approval System",
+    summary: "Reference app showing state-machine driven approvals with RBAC, audit trail, notifications, and jobs.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/workflow-system",
+    tags: ["workflow", "approval", "state-machine", "rbac"],
+    body: `## Entities
+
+- WorkflowDefinition, WorkflowStep, WorkflowInstance, Approval.
+- State machine expressed in \`src/state-machine\` with allowed transitions and role gates.
+
+## Contracts
+
+- \`workflow.definition.create\`, \`workflow.instance.start\`, \`workflow.step.approve\`, \`workflow.step.reject\`, \`workflow.instance.comment\`.
+- Policies enforced via Identity/RBAC module; audit trail emitted on each transition.
+
+## Events & Jobs
+
+- Emits \`workflow.instance.started\`, \`workflow.step.completed\`, \`workflow.step.rejected\`, \`workflow.instance.finished\`.
+- Reminder jobs can be scheduled via @contractspec/lib.jobs for pending approvals.
+
+## UI / Presentations
+
+- Dashboard, definition list/editor, instance detail with action buttons derived from state machine.
+- Templates registered in Studio Template Registry under \`workflow-system\`.
+
+## Notes
+
+- Keep transitions declarative to enable safe regeneration; role guards live in spec.
+- Use Notification Center for approval requests and outcomes; attach files via Files module if needed.
+`
+  },
+  {
+    id: "docs.examples.workflow-system.goal",
+    title: "Workflow System — Goal",
+    summary: "Why the workflow/approval template exists and outcomes it targets.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/workflow-system/goal",
+    tags: ["workflow", "goal"],
+    body: `## Why it matters
+- Provides a regenerable, role-gated approval engine using declarative state machines.
+- Keeps workflow rules consistent across UI/API/events with auditability.
+
+## Business/Product goal
+- Enable approvals with clear transitions, reminders, and notifications.
+- Support compliance via Audit Trail and Feature Flags for staged changes.
+
+## Success criteria
+- State changes are declarative and regenerate cleanly.
+- Every transition emits auditable events and respects RBAC guards.`
+  },
+  {
+    id: "docs.examples.workflow-system.usage",
+    title: "Workflow System — Usage",
+    summary: "How to configure workflows, transitions, and regenerate safely.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/workflow-system/usage",
+    tags: ["workflow", "usage"],
+    body: `## Setup
+1) Define WorkflowDefinition steps and allowed transitions with role gates in spec.
+2) Seed sample workflows/instances (if provided) or create via UI; enable reminders via Jobs.
+
+## Extend & regenerate
+1) Add steps/transitions or approval conditions in spec; include PII paths if comments/files.
+2) Regenerate to sync UI action buttons and API/state machine behavior.
+3) Use Feature Flags to trial new transitions or escalation rules.
+
+## Guardrails
+- Emit events for every transition; log to Audit Trail.
+- Use Notifications for approvals/rejections; schedule reminders for pending steps.
+- Keep transitions declarative; avoid imperative branching in handlers.`
+  },
+  {
+    id: "docs.examples.workflow-system.constraints",
+    title: "Workflow System — Constraints & Safety",
+    summary: "Internal guardrails for state machines, RBAC, and regeneration semantics.",
+    kind: "reference",
+    visibility: "internal",
+    route: "/docs/examples/workflow-system/constraints",
+    tags: ["workflow", "constraints", "internal"],
+    body: `## Constraints
+- State machine (steps/transitions) must stay declarative in spec; no hidden code paths.
+- Events to emit: instance.started, step.completed/rejected, instance.finished.
+- Regeneration must not change approval logic without explicit spec diff.
+
+## PII & Compliance
+- Mark any PII in comments/attachments; redact in markdown/JSON.
+- Ensure Audit Trail captures every transition; Notifications for approvals/rejections.
+
+## Verification
+- Add fixtures for transition changes and role gates.
+- Validate reminders (Jobs) stay aligned with pending states after regeneration.
+- Use Feature Flags for new transitions/escalation rules; default safe/off.`
+  }
+];
+registerDocBlocks(workflowSystemDocBlocks);

package/dist/browser/docs/workflow-system.docblock.js

@@ -0,0 +1,103 @@
+// src/docs/workflow-system.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var workflowSystemDocBlocks = [
+  {
+    id: "docs.examples.workflow-system",
+    title: "Workflow / Approval System",
+    summary: "Reference app showing state-machine driven approvals with RBAC, audit trail, notifications, and jobs.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/examples/workflow-system",
+    tags: ["workflow", "approval", "state-machine", "rbac"],
+    body: `## Entities
+
+- WorkflowDefinition, WorkflowStep, WorkflowInstance, Approval.
+- State machine expressed in \`src/state-machine\` with allowed transitions and role gates.
+
+## Contracts
+
+- \`workflow.definition.create\`, \`workflow.instance.start\`, \`workflow.step.approve\`, \`workflow.step.reject\`, \`workflow.instance.comment\`.
+- Policies enforced via Identity/RBAC module; audit trail emitted on each transition.
+
+## Events & Jobs
+
+- Emits \`workflow.instance.started\`, \`workflow.step.completed\`, \`workflow.step.rejected\`, \`workflow.instance.finished\`.
+- Reminder jobs can be scheduled via @contractspec/lib.jobs for pending approvals.
+
+## UI / Presentations
+
+- Dashboard, definition list/editor, instance detail with action buttons derived from state machine.
+- Templates registered in Studio Template Registry under \`workflow-system\`.
+
+## Notes
+
+- Keep transitions declarative to enable safe regeneration; role guards live in spec.
+- Use Notification Center for approval requests and outcomes; attach files via Files module if needed.
+`
+  },
+  {
+    id: "docs.examples.workflow-system.goal",
+    title: "Workflow System — Goal",
+    summary: "Why the workflow/approval template exists and outcomes it targets.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/workflow-system/goal",
+    tags: ["workflow", "goal"],
+    body: `## Why it matters
+- Provides a regenerable, role-gated approval engine using declarative state machines.
+- Keeps workflow rules consistent across UI/API/events with auditability.
+
+## Business/Product goal
+- Enable approvals with clear transitions, reminders, and notifications.
+- Support compliance via Audit Trail and Feature Flags for staged changes.
+
+## Success criteria
+- State changes are declarative and regenerate cleanly.
+- Every transition emits auditable events and respects RBAC guards.`
+  },
+  {
+    id: "docs.examples.workflow-system.usage",
+    title: "Workflow System — Usage",
+    summary: "How to configure workflows, transitions, and regenerate safely.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/workflow-system/usage",
+    tags: ["workflow", "usage"],
+    body: `## Setup
+1) Define WorkflowDefinition steps and allowed transitions with role gates in spec.
+2) Seed sample workflows/instances (if provided) or create via UI; enable reminders via Jobs.
+
+## Extend & regenerate
+1) Add steps/transitions or approval conditions in spec; include PII paths if comments/files.
+2) Regenerate to sync UI action buttons and API/state machine behavior.
+3) Use Feature Flags to trial new transitions or escalation rules.
+
+## Guardrails
+- Emit events for every transition; log to Audit Trail.
+- Use Notifications for approvals/rejections; schedule reminders for pending steps.
+- Keep transitions declarative; avoid imperative branching in handlers.`
+  },
+  {
+    id: "docs.examples.workflow-system.constraints",
+    title: "Workflow System — Constraints & Safety",
+    summary: "Internal guardrails for state machines, RBAC, and regeneration semantics.",
+    kind: "reference",
+    visibility: "internal",
+    route: "/docs/examples/workflow-system/constraints",
+    tags: ["workflow", "constraints", "internal"],
+    body: `## Constraints
+- State machine (steps/transitions) must stay declarative in spec; no hidden code paths.
+- Events to emit: instance.started, step.completed/rejected, instance.finished.
+- Regeneration must not change approval logic without explicit spec diff.
+
+## PII & Compliance
+- Mark any PII in comments/attachments; redact in markdown/JSON.
+- Ensure Audit Trail captures every transition; Notifications for approvals/rejections.
+
+## Verification
+- Add fixtures for transition changes and role gates.
+- Validate reminders (Jobs) stay aligned with pending states after regeneration.
+- Use Feature Flags for new transitions/escalation rules; default safe/off.`
+  }
+];
+registerDocBlocks(workflowSystemDocBlocks);