// src/components/docs/specs/SpecsWorkflowsPage.tsx
import Link from "@contractspec/lib.ui-link";
import { ChevronRight } from "lucide-react";
import { jsx, jsxs } from "react/jsx-runtime";
function SpecsWorkflowsPage() {
  return /* @__PURE__ */ jsxs("div", {
    className: "space-y-8",
    children: [
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h1", {
            className: "text-4xl font-bold",
            children: "Workflows"
          }),
          /* @__PURE__ */ jsxs("p", {
            className: "text-muted-foreground",
            children: [
              "A ",
              /* @__PURE__ */ jsx("strong", {
                children: "WorkflowSpec"
              }),
              " orchestrates multi-step processes. It defines the sequence of operations, handles failures with retries and compensation, and provides observability into long-running tasks."
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Core concepts"
          }),
          /* @__PURE__ */ jsxs("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsxs("div", {
                children: [
                  /* @__PURE__ */ jsx("h3", {
                    className: "text-lg font-semibold",
                    children: "Identifiers"
                  }),
                  /* @__PURE__ */ jsxs("p", {
                    className: "text-muted-foreground",
                    children: [
                      "Each workflow has a unique",
                      " ",
                      /* @__PURE__ */ jsx("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "workflowId"
                      }),
                      " ",
                      "and a",
                      " ",
                      /* @__PURE__ */ jsx("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "version"
                      }),
                      ". This allows you to run multiple versions of the same workflow simultaneously during migrations or A/B tests."
                    ]
                  })
                ]
              }),
              /* @__PURE__ */ jsxs("div", {
                children: [
                  /* @__PURE__ */ jsx("h3", {
                    className: "text-lg font-semibold",
                    children: "Steps"
                  }),
                  /* @__PURE__ */ jsxs("p", {
                    className: "text-muted-foreground",
                    children: [
                      "A workflow is composed of ",
                      /* @__PURE__ */ jsx("strong", {
                        children: "steps"
                      }),
                      ". Each step invokes a",
                      " ",
                      /* @__PURE__ */ jsx(Link, {
                        href: "/docs/specs/capabilities",
                        className: "text-violet-400 hover:text-violet-300",
                        children: "CapabilitySpec"
                      }),
                      ", passes inputs, and receives outputs. Steps can run sequentially or in parallel."
                    ]
                  })
                ]
              }),
              /* @__PURE__ */ jsxs("div", {
                children: [
                  /* @__PURE__ */ jsx("h3", {
                    className: "text-lg font-semibold",
                    children: "Transitions"
                  }),
                  /* @__PURE__ */ jsxs("p", {
                    className: "text-muted-foreground",
                    children: [
                      /* @__PURE__ */ jsx("strong", {
                        children: "Transitions"
                      }),
                      ' define the flow between steps. They can be conditional (e.g., "if payment succeeds, go to step 3; otherwise, go to step 5") or unconditional.'
                    ]
                  })
                ]
              }),
              /* @__PURE__ */ jsxs("div", {
                children: [
                  /* @__PURE__ */ jsx("h3", {
                    className: "text-lg font-semibold",
                    children: "Retries"
                  }),
                  /* @__PURE__ */ jsx("p", {
                    className: "text-muted-foreground",
                    children: "If a step fails, the workflow can retry it with exponential backoff. You specify the maximum number of retries and the backoff strategy in the spec."
                  })
                ]
              }),
              /* @__PURE__ */ jsxs("div", {
                children: [
                  /* @__PURE__ */ jsx("h3", {
                    className: "text-lg font-semibold",
                    children: "Compensation"
                  }),
                  /* @__PURE__ */ jsxs("p", {
                    className: "text-muted-foreground",
                    children: [
                      "When a workflow fails partway through,",
                      " ",
                      /* @__PURE__ */ jsx("strong", {
                        children: "compensation"
                      }),
                      " steps undo the effects of completed steps (e.g., refunding a payment, releasing a reservation). This ensures consistency even in failure scenarios."
                    ]
                  })
                ]
              }),
              /* @__PURE__ */ jsxs("div", {
                children: [
                  /* @__PURE__ */ jsx("h3", {
                    className: "text-lg font-semibold",
                    children: "SLAs"
                  }),
                  /* @__PURE__ */ jsx("p", {
                    className: "text-muted-foreground",
                    children: "You can define Service Level Agreements (SLAs) for each step or the entire workflow. If a step exceeds its SLA, the system can trigger alerts or escalations."
                  })
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Example WorkflowSpec (TypeScript)"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Here's a simplified example of a payment workflow in TypeScript:"
          }),
          /* @__PURE__ */ jsx("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx("pre", {
              children: `import { defineWorkflow } from '@contractspec/lib.contracts-spec/workflow';
import { ValidatePaymentMethod, ChargePayment, SendEmail } from './specs';

export const PaymentFlow = defineWorkflow({
  meta: {
    key: 'payment.flow',
    version: '1.0.0',
    description: 'End-to-end payment processing',
    owners: ['team-payments'],
    tags: ['payments'],
    stability: 'stable',
  },
  steps: [
    {
      id: 'validate-payment',
      operation: ValidatePaymentMethod,
      inputs: (ctx, input) => ({
        userId: ctx.userId,
        paymentMethodId: input.paymentMethodId,
      }),
      retry: {
        maxAttempts: 3,
        backoff: 'exponential',
      },
      onSuccess: 'charge-payment',
      onFailure: 'notify-user',
    },
    {
      id: 'charge-payment',
      operation: ChargePayment,
      inputs: (ctx, input, steps) => ({
        amount: input.amount,
        paymentMethodId: input.paymentMethodId,
      }),
      compensation: 'refund-payment',
      onSuccess: 'send-receipt',
      onFailure: 'notify-admin',
    },
    {
      id: 'send-receipt',
      operation: SendEmail,
      inputs: (ctx, input, steps) => ({
        to: ctx.userEmail,
        template: 'payment-receipt',
        data: steps['charge-payment'].output,
      }),
    },
  ],
  sla: {
    maxDuration: 30000, // milliseconds
    alertOnBreach: true,
  },
});`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Triggers"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Workflows can be triggered in several ways:"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Manual invocation"
                  }),
                  " – A user or system calls the workflow via an API endpoint."
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Event-driven"
                  }),
                  " – The workflow starts automatically when a specific event occurs (e.g., a new order is created)."
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Scheduled"
                  }),
                  " – The workflow runs on a cron schedule (e.g., nightly batch processing)."
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Chained"
                  }),
                  " – One workflow can invoke another as a step."
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Monitoring and versioning"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "ContractSpec automatically instruments workflows with telemetry. You can view:"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx("li", {
                children: "Real-time execution status for each step"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Historical run data and success/failure rates"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Latency distributions and SLA compliance"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Compensation events and retry attempts"
              })
            ]
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "When you update a workflow, you increment its version. Running workflows continue on their original version, while new invocations use the latest version. This allows safe, zero-downtime deployments."
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Best practices"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx("li", {
                children: "Keep steps idempotent – they should be safe to retry without side effects."
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Define compensation for any step that modifies external state."
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Use meaningful step IDs that describe the operation."
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Set realistic SLAs and monitor them in production."
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Test failure scenarios locally before deploying."
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "flex items-center gap-4 pt-4",
        children: [
          /* @__PURE__ */ jsx(Link, {
            href: "/docs/specs/capabilities",
            className: "btn-ghost",
            children: "Previous: Capabilities"
          }),
          /* @__PURE__ */ jsxs(Link, {
            href: "/docs/safety",
            className: "btn-primary",
            children: [
              "Next: Safety Features ",
              /* @__PURE__ */ jsx(ChevronRight, {
                size: 16
              })
            ]
          })
        ]
      })
    ]
  });
}
export {
  SpecsWorkflowsPage
};
