// @bun
// src/components/docs/specs/SpecsOverviewPage.tsx
import Link from "@contractspec/lib.ui-link";
import { ChevronRight } from "lucide-react";
import { jsx, jsxs } from "react/jsx-runtime";
function SpecsOverviewPage() {
  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: "Specifications Overview"
          }),
          /* @__PURE__ */ jsxs("p", {
            className: "text-muted-foreground",
            children: [
              "ContractSpec is built on a ",
              /* @__PURE__ */ jsx("strong", {
                children: "spec-first"
              }),
              " philosophy. You define declarative TypeScript specifications that describe what your application can do. Runtime adapters automatically serve these specs as type-safe API endpoints (REST, GraphQL, MCP), enforce policies, and validate inputs/outputs\u2014no code generation required."
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Why spec-first matters"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Traditional development requires writing and maintaining separate code for APIs, databases, UI components, validation logic, and access control. This approach leads to:"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx("li", {
                children: "Duplication across front-end and back-end"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Type mismatches and runtime errors"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Security vulnerabilities from inconsistent policy enforcement"
              }),
              /* @__PURE__ */ jsx("li", {
                children: "High maintenance burden when requirements change"
              })
            ]
          }),
          /* @__PURE__ */ jsxs("p", {
            className: "text-muted-foreground",
            children: [
              "With ContractSpec, you define your application's operations (Commands/Queries), workflows, and policies in pure TypeScript. Runtime adapters ensure consistency, type safety, and policy enforcement across your entire stack\u2014the spec ",
              /* @__PURE__ */ jsx("em", {
                children: "is"
              }),
              " the implementation."
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Specification types"
          }),
          /* @__PURE__ */ jsx("div", {
            className: "border-border/50 overflow-x-auto rounded-lg border",
            children: /* @__PURE__ */ jsxs("table", {
              className: "w-full text-left text-sm",
              children: [
                /* @__PURE__ */ jsx("thead", {
                  className: "bg-card/50",
                  children: /* @__PURE__ */ jsxs("tr", {
                    className: "border-border/50 border-b",
                    children: [
                      /* @__PURE__ */ jsx("th", {
                        className: "px-4 py-3 font-semibold",
                        children: "Spec Type"
                      }),
                      /* @__PURE__ */ jsx("th", {
                        className: "px-4 py-3 font-semibold",
                        children: "Purpose"
                      }),
                      /* @__PURE__ */ jsx("th", {
                        className: "px-4 py-3 font-semibold",
                        children: "Generates"
                      })
                    ]
                  })
                }),
                /* @__PURE__ */ jsxs("tbody", {
                  className: "divide-border/50 divide-y",
                  children: [
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: /* @__PURE__ */ jsx(Link, {
                            href: "/docs/specs/capabilities",
                            className: "text-violet-400 hover:text-violet-300",
                            children: /* @__PURE__ */ jsx("strong", {
                              children: "CapabilitySpec"
                            })
                          })
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Defines what your application can do: operations (Commands/Queries), their inputs, outputs, policies, and side effects."
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Runtime-served REST/GraphQL/MCP endpoints, Zod validation, policy enforcement"
                        })
                      ]
                    }),
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: /* @__PURE__ */ jsx("strong", {
                            children: "DataViewSpec"
                          })
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Describes how data should be queried, filtered, sorted, and presented to users."
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Database queries, list/detail views, search interfaces"
                        })
                      ]
                    }),
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: /* @__PURE__ */ jsx(Link, {
                            href: "/docs/specs/workflows",
                            className: "text-violet-400 hover:text-violet-300",
                            children: /* @__PURE__ */ jsx("strong", {
                              children: "WorkflowSpec"
                            })
                          })
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Orchestrates multi-step processes with retries, compensation, and monitoring."
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Workflow engine, state machines, retry logic, observability hooks"
                        })
                      ]
                    }),
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: /* @__PURE__ */ jsx("strong", {
                            children: "PolicySpec"
                          })
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Defines who can do what, when, and under what conditions. Supports ABAC and PII rules."
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Policy decision points, access control middleware, audit logs"
                        })
                      ]
                    }),
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: /* @__PURE__ */ jsx("strong", {
                            children: "OverlaySpec"
                          })
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Allows safe, signed customization of UI layouts and field visibility by tenants or users."
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Personalized UI components, layout variations, conditional rendering"
                        })
                      ]
                    }),
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: /* @__PURE__ */ jsx("strong", {
                            children: "TelemetrySpec"
                          })
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Specifies what metrics, logs, and traces to collect for observability."
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Instrumentation code, dashboards, alerting rules"
                        })
                      ]
                    }),
                    /* @__PURE__ */ jsxs("tr", {
                      children: [
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: /* @__PURE__ */ jsx(Link, {
                            href: "/docs/safety/migrations",
                            className: "text-violet-400 hover:text-violet-300",
                            children: /* @__PURE__ */ jsx("strong", {
                              children: "MigrationSpec"
                            })
                          })
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Manages incremental, reversible schema and data migrations."
                        }),
                        /* @__PURE__ */ jsx("td", {
                          className: "px-4 py-3 align-top",
                          children: "Migration scripts, rollback procedures, version tracking"
                        })
                      ]
                    })
                  ]
                })
              ]
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "How specs work together"
          }),
          /* @__PURE__ */ jsxs("p", {
            className: "text-muted-foreground",
            children: [
              "Specs compose naturally. A ",
              /* @__PURE__ */ jsx("strong", {
                children: "WorkflowSpec"
              }),
              " can invoke multiple ",
              /* @__PURE__ */ jsx("strong", {
                children: "CapabilitySpecs"
              }),
              ". A",
              " ",
              /* @__PURE__ */ jsx("strong", {
                children: "DataViewSpec"
              }),
              " respects ",
              /* @__PURE__ */ jsx("strong", {
                children: "PolicySpecs"
              }),
              " to filter sensitive fields. An ",
              /* @__PURE__ */ jsx("strong", {
                children: "OverlaySpec"
              }),
              " can hide or rearrange UI elements generated from a ",
              /* @__PURE__ */ jsx("strong", {
                children: "CapabilitySpec"
              }),
              ", but only within the bounds allowed by the underlying policy."
            ]
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "This composability means you can build complex applications from simple, reusable building blocks\u2014all while maintaining type safety and policy enforcement."
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Next steps"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Explore each specification type in detail using the links in the table above, or continue with the core concepts:"
          }),
          /* @__PURE__ */ jsxs("div", {
            className: "flex flex-wrap gap-4 pt-4",
            children: [
              /* @__PURE__ */ jsxs(Link, {
                href: "/docs/specs/capabilities",
                className: "btn-primary",
                children: [
                  "Capabilities ",
                  /* @__PURE__ */ jsx(ChevronRight, {
                    size: 16,
                    className: "inline"
                  })
                ]
              }),
              /* @__PURE__ */ jsxs(Link, {
                href: "/docs/specs/workflows",
                className: "btn-ghost",
                children: [
                  "Workflows ",
                  /* @__PURE__ */ jsx(ChevronRight, {
                    size: 16,
                    className: "inline"
                  })
                ]
              }),
              /* @__PURE__ */ jsxs(Link, {
                href: "/docs/safety",
                className: "btn-ghost",
                children: [
                  "Safety Features ",
                  /* @__PURE__ */ jsx(ChevronRight, {
                    size: 16,
                    className: "inline"
                  })
                ]
              })
            ]
          })
        ]
      })
    ]
  });
}

// src/components/docs/specs/SpecsCapabilitiesPage.tsx
import Link2 from "@contractspec/lib.ui-link";
import { ChevronRight as ChevronRight2 } from "lucide-react";
import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
function SpecsCapabilitiesPage() {
  return /* @__PURE__ */ jsxs2("div", {
    className: "space-y-8",
    children: [
      /* @__PURE__ */ jsxs2("div", {
        className: "space-y-2",
        children: [
          /* @__PURE__ */ jsx2("h1", {
            className: "text-4xl font-bold",
            children: "Capabilities"
          }),
          /* @__PURE__ */ jsx2("p", {
            className: "text-muted-foreground text-lg",
            children: "Capabilities are the core building block of ContractSpec. They define what your app can do."
          })
        ]
      }),
      /* @__PURE__ */ jsxs2("div", {
        className: "space-y-6",
        children: [
          /* @__PURE__ */ jsxs2("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsx2("h2", {
                className: "text-2xl font-bold",
                children: "Overview"
              }),
              /* @__PURE__ */ jsx2("p", {
                className: "text-muted-foreground",
                children: "A ContractSpec (or Capability) is a typed, declarative description of an operation. It defines the operation's name, version, inputs, outputs, policies, and side effects. Runtime adapters automatically serve these as REST/GraphQL/MCP endpoints with full validation and policy enforcement."
              })
            ]
          }),
          /* @__PURE__ */ jsxs2("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsx2("h2", {
                className: "text-2xl font-bold",
                children: "Defining a Command (Write)"
              }),
              /* @__PURE__ */ jsx2("div", {
                className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
                children: /* @__PURE__ */ jsx2("pre", {
                  children: `import { defineCommand } from '@contractspec/lib.contracts-spec';
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';

const TransferFundsInput = new SchemaModel({
  name: 'TransferFundsInput',
  fields: {
    recipient: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
    amount: { type: ScalarTypeEnum.PositiveNumber(), isOptional: false },
  },
});

const TransferFundsOutput = new SchemaModel({
  name: 'TransferFundsOutput',
  fields: {
    transactionId: { type: ScalarTypeEnum.String(), isOptional: false },
    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false },
  },
});

export const TransferFunds = defineCommand({
  meta: {
    key: 'wallet.transferFunds',
    version: '1.0.0',
    description: 'Transfer funds to another user',
    goal: 'Enable peer-to-peer payments',
    context: 'Requires sufficient balance',
    owners: ['team-payments'],
    tags: ['payments'],
    stability: 'stable',
  },
  io: {
    input: TransferFundsInput,
    output: TransferFundsOutput,
  },
  policy: {
    auth: 'user',
    flags: ['payments_enabled'],
  },
});`
                })
              })
            ]
          }),
          /* @__PURE__ */ jsxs2("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsx2("h2", {
                className: "text-2xl font-bold",
                children: "Schema Types"
              }),
              /* @__PURE__ */ jsxs2("p", {
                className: "text-muted-foreground",
                children: [
                  "ContractSpec uses ",
                  /* @__PURE__ */ jsx2("code", {
                    children: "@contractspec/lib.schema"
                  }),
                  " for I/O definitions. This provides Zod validation, GraphQL types, and JSON Schema from a single source."
                ]
              }),
              /* @__PURE__ */ jsxs2("ul", {
                className: "text-muted-foreground space-y-2",
                children: [
                  /* @__PURE__ */ jsxs2("li", {
                    children: [
                      "\u2022",
                      " ",
                      /* @__PURE__ */ jsx2("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "ScalarTypeEnum.NonEmptyString()"
                      }),
                      " ",
                      "- Non-empty text"
                    ]
                  }),
                  /* @__PURE__ */ jsxs2("li", {
                    children: [
                      "\u2022",
                      " ",
                      /* @__PURE__ */ jsx2("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "ScalarTypeEnum.PositiveNumber()"
                      }),
                      " ",
                      "- Positive numbers"
                    ]
                  }),
                  /* @__PURE__ */ jsxs2("li", {
                    children: [
                      "\u2022",
                      " ",
                      /* @__PURE__ */ jsx2("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "ScalarTypeEnum.DateTime()"
                      }),
                      " ",
                      "- ISO 8601 timestamps"
                    ]
                  }),
                  /* @__PURE__ */ jsxs2("li", {
                    children: [
                      "\u2022",
                      " ",
                      /* @__PURE__ */ jsx2("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "ScalarTypeEnum.Email()"
                      }),
                      " ",
                      "- Valid email addresses"
                    ]
                  }),
                  /* @__PURE__ */ jsxs2("li", {
                    children: [
                      "\u2022",
                      " ",
                      /* @__PURE__ */ jsx2("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "defineEnum(...)"
                      }),
                      " ",
                      "- Type-safe enums"
                    ]
                  })
                ]
              })
            ]
          }),
          /* @__PURE__ */ jsx2("div", {
            className: "flex items-center gap-4 pt-4",
            children: /* @__PURE__ */ jsxs2(Link2, {
              href: "/docs/specs/dataviews",
              className: "btn-primary",
              children: [
                "Next: DataViews ",
                /* @__PURE__ */ jsx2(ChevronRight2, {
                  size: 16
                })
              ]
            })
          })
        ]
      })
    ]
  });
}

// src/components/docs/specs/SpecsDataViewsPage.tsx
import Link3 from "@contractspec/lib.ui-link";
import { ChevronRight as ChevronRight3 } from "lucide-react";
import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
function SpecsDataViewsPage() {
  return /* @__PURE__ */ jsxs3("div", {
    className: "space-y-8",
    children: [
      /* @__PURE__ */ jsxs3("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx3("h1", {
            className: "text-4xl font-bold",
            children: "DataViews"
          }),
          /* @__PURE__ */ jsxs3("p", {
            className: "text-muted-foreground",
            children: [
              "A ",
              /* @__PURE__ */ jsx3("strong", {
                children: "DataViewSpec"
              }),
              " describes how data should be queried, filtered, sorted, and presented to users. Runtime adapters execute optimized database queries and serve list views, detail views, and search interfaces while respecting policy constraints."
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs3("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx3("h2", {
            className: "text-2xl font-bold",
            children: "Core concepts"
          }),
          /* @__PURE__ */ jsxs3("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsxs3("div", {
                children: [
                  /* @__PURE__ */ jsx3("h3", {
                    className: "text-lg font-semibold",
                    children: "Data sources"
                  }),
                  /* @__PURE__ */ jsx3("p", {
                    className: "text-muted-foreground",
                    children: "A DataView connects to one or more data sources\u2014databases, APIs, or other capabilities. You specify the source and the fields you want to expose."
                  })
                ]
              }),
              /* @__PURE__ */ jsxs3("div", {
                children: [
                  /* @__PURE__ */ jsx3("h3", {
                    className: "text-lg font-semibold",
                    children: "Filtering"
                  }),
                  /* @__PURE__ */ jsx3("p", {
                    className: "text-muted-foreground",
                    children: `Define filters that users can apply to narrow down results. Filters can be simple (e.g., "status equals 'active'") or complex (e.g., "created within the last 30 days AND assigned to current user").`
                  })
                ]
              }),
              /* @__PURE__ */ jsxs3("div", {
                children: [
                  /* @__PURE__ */ jsx3("h3", {
                    className: "text-lg font-semibold",
                    children: "Sorting"
                  }),
                  /* @__PURE__ */ jsx3("p", {
                    className: "text-muted-foreground",
                    children: "Specify which fields can be sorted and the default sort order. ContractSpec generates efficient database queries with proper indexes."
                  })
                ]
              }),
              /* @__PURE__ */ jsxs3("div", {
                children: [
                  /* @__PURE__ */ jsx3("h3", {
                    className: "text-lg font-semibold",
                    children: "Pagination"
                  }),
                  /* @__PURE__ */ jsx3("p", {
                    className: "text-muted-foreground",
                    children: "DataViews automatically support pagination to handle large datasets. You can configure page size limits and cursor-based or offset-based pagination."
                  })
                ]
              }),
              /* @__PURE__ */ jsxs3("div", {
                children: [
                  /* @__PURE__ */ jsx3("h3", {
                    className: "text-lg font-semibold",
                    children: "Aggregations"
                  }),
                  /* @__PURE__ */ jsx3("p", {
                    className: "text-muted-foreground",
                    children: "Compute aggregates like counts, sums, averages, and group-by operations. These are useful for dashboards and summary views."
                  })
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs3("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx3("h2", {
            className: "text-2xl font-bold",
            children: "Example DataViewSpec"
          }),
          /* @__PURE__ */ jsx3("p", {
            className: "text-muted-foreground",
            children: "Here's a DataView for listing orders in TypeScript:"
          }),
          /* @__PURE__ */ jsx3("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx3("pre", {
              children: `import { defineDataView } from '@contractspec/lib.contracts-spec';
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';

export const OrderList = defineDataView({
  meta: {
    key: 'order.list',
    version: '1.0.0',
    description: 'List of recent orders',
  },
  source: {
    type: 'database',
    table: 'orders',
  },
  fields: [
    { name: 'orderId', type: 'uuid', sortable: true },
    { name: 'customerName', type: 'string', searchable: true },
    { name: 'total', type: 'number', sortable: true },
    { 
      name: 'status', 
      type: 'enum', 
      values: ['pending', 'processing', 'shipped'],
      filterable: true 
    },
    { 
      name: 'createdAt', 
      type: 'timestamp', 
      sortable: true, 
      defaultSort: 'desc' 
    },
  ],
  filters: [
    { name: 'status', field: 'status', operator: 'in' },
    { name: 'dateRange', field: 'createdAt', operator: 'between' },
    { name: 'minTotal', field: 'total', operator: 'gte' },
  ],
  pagination: {
    type: 'cursor',
    defaultPageSize: 50,
    maxPageSize: 200,
  },
});`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs3("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx3("h2", {
            className: "text-2xl font-bold",
            children: "Policy integration"
          }),
          /* @__PURE__ */ jsxs3("p", {
            className: "text-muted-foreground",
            children: [
              "DataViews automatically enforce",
              " ",
              /* @__PURE__ */ jsx3(Link3, {
                href: "/docs/specs/policy",
                className: "text-violet-400 hover:text-violet-300",
                children: "PolicySpecs"
              }),
              ". If a user doesn't have permission to see certain fields, those fields are automatically filtered out or redacted. If a user can only see their own data, the query is automatically scoped."
            ]
          }),
          /* @__PURE__ */ jsx3("p", {
            className: "text-muted-foreground",
            children: "This means you define the data view once, and it works correctly for all users based on their permissions\u2014no need to write separate queries for different roles."
          })
        ]
      }),
      /* @__PURE__ */ jsxs3("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx3("h2", {
            className: "text-2xl font-bold",
            children: "Served outputs"
          }),
          /* @__PURE__ */ jsx3("p", {
            className: "text-muted-foreground",
            children: "From a DataViewSpec, ContractSpec serves:"
          }),
          /* @__PURE__ */ jsxs3("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs3("li", {
                children: [
                  /* @__PURE__ */ jsx3("strong", {
                    children: "Database queries"
                  }),
                  " \u2013 Optimized SQL or NoSQL queries executed at runtime"
                ]
              }),
              /* @__PURE__ */ jsxs3("li", {
                children: [
                  /* @__PURE__ */ jsx3("strong", {
                    children: "API endpoints"
                  }),
                  " \u2013 RESTful or GraphQL endpoints for fetching data"
                ]
              }),
              /* @__PURE__ */ jsxs3("li", {
                children: [
                  /* @__PURE__ */ jsx3("strong", {
                    children: "UI components"
                  }),
                  " \u2013 List views, tables, cards, and detail views"
                ]
              }),
              /* @__PURE__ */ jsxs3("li", {
                children: [
                  /* @__PURE__ */ jsx3("strong", {
                    children: "Search interfaces"
                  }),
                  " \u2013 Full-text search with autocomplete"
                ]
              }),
              /* @__PURE__ */ jsxs3("li", {
                children: [
                  /* @__PURE__ */ jsx3("strong", {
                    children: "Export functions"
                  }),
                  " \u2013 CSV, JSON, or Excel exports"
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs3("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx3("h2", {
            className: "text-2xl font-bold",
            children: "Best practices"
          }),
          /* @__PURE__ */ jsxs3("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx3("li", {
                children: "Only expose fields that users actually need\u2014this improves performance and security."
              }),
              /* @__PURE__ */ jsx3("li", {
                children: "Use appropriate indexes for sortable and filterable fields."
              }),
              /* @__PURE__ */ jsx3("li", {
                children: "Set reasonable pagination limits to prevent performance issues."
              }),
              /* @__PURE__ */ jsx3("li", {
                children: "Use aggregations sparingly\u2014they can be expensive on large datasets."
              }),
              /* @__PURE__ */ jsx3("li", {
                children: "Test DataViews with realistic data volumes to ensure they perform well."
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs3("div", {
        className: "flex items-center gap-4 pt-4",
        children: [
          /* @__PURE__ */ jsx3(Link3, {
            href: "/docs/specs/capabilities",
            className: "btn-ghost",
            children: "Previous: Capabilities"
          }),
          /* @__PURE__ */ jsxs3(Link3, {
            href: "/docs/specs/workflows",
            className: "btn-primary",
            children: [
              "Next: Workflows ",
              /* @__PURE__ */ jsx3(ChevronRight3, {
                size: 16
              })
            ]
          })
        ]
      })
    ]
  });
}

// src/components/docs/specs/SpecsWorkflowsPage.tsx
import Link4 from "@contractspec/lib.ui-link";
import { ChevronRight as ChevronRight4 } from "lucide-react";
import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
function SpecsWorkflowsPage() {
  return /* @__PURE__ */ jsxs4("div", {
    className: "space-y-8",
    children: [
      /* @__PURE__ */ jsxs4("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx4("h1", {
            className: "text-4xl font-bold",
            children: "Workflows"
          }),
          /* @__PURE__ */ jsxs4("p", {
            className: "text-muted-foreground",
            children: [
              "A ",
              /* @__PURE__ */ jsx4("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__ */ jsxs4("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx4("h2", {
            className: "text-2xl font-bold",
            children: "Core concepts"
          }),
          /* @__PURE__ */ jsxs4("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsxs4("div", {
                children: [
                  /* @__PURE__ */ jsx4("h3", {
                    className: "text-lg font-semibold",
                    children: "Identifiers"
                  }),
                  /* @__PURE__ */ jsxs4("p", {
                    className: "text-muted-foreground",
                    children: [
                      "Each workflow has a unique",
                      " ",
                      /* @__PURE__ */ jsx4("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "workflowId"
                      }),
                      " ",
                      "and a",
                      " ",
                      /* @__PURE__ */ jsx4("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__ */ jsxs4("div", {
                children: [
                  /* @__PURE__ */ jsx4("h3", {
                    className: "text-lg font-semibold",
                    children: "Steps"
                  }),
                  /* @__PURE__ */ jsxs4("p", {
                    className: "text-muted-foreground",
                    children: [
                      "A workflow is composed of ",
                      /* @__PURE__ */ jsx4("strong", {
                        children: "steps"
                      }),
                      ". Each step invokes a",
                      " ",
                      /* @__PURE__ */ jsx4(Link4, {
                        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__ */ jsxs4("div", {
                children: [
                  /* @__PURE__ */ jsx4("h3", {
                    className: "text-lg font-semibold",
                    children: "Transitions"
                  }),
                  /* @__PURE__ */ jsxs4("p", {
                    className: "text-muted-foreground",
                    children: [
                      /* @__PURE__ */ jsx4("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__ */ jsxs4("div", {
                children: [
                  /* @__PURE__ */ jsx4("h3", {
                    className: "text-lg font-semibold",
                    children: "Retries"
                  }),
                  /* @__PURE__ */ jsx4("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__ */ jsxs4("div", {
                children: [
                  /* @__PURE__ */ jsx4("h3", {
                    className: "text-lg font-semibold",
                    children: "Compensation"
                  }),
                  /* @__PURE__ */ jsxs4("p", {
                    className: "text-muted-foreground",
                    children: [
                      "When a workflow fails partway through,",
                      " ",
                      /* @__PURE__ */ jsx4("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__ */ jsxs4("div", {
                children: [
                  /* @__PURE__ */ jsx4("h3", {
                    className: "text-lg font-semibold",
                    children: "SLAs"
                  }),
                  /* @__PURE__ */ jsx4("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__ */ jsxs4("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx4("h2", {
            className: "text-2xl font-bold",
            children: "Example WorkflowSpec (TypeScript)"
          }),
          /* @__PURE__ */ jsx4("p", {
            className: "text-muted-foreground",
            children: "Here's a simplified example of a payment workflow in TypeScript:"
          }),
          /* @__PURE__ */ jsx4("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx4("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__ */ jsxs4("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx4("h2", {
            className: "text-2xl font-bold",
            children: "Triggers"
          }),
          /* @__PURE__ */ jsx4("p", {
            className: "text-muted-foreground",
            children: "Workflows can be triggered in several ways:"
          }),
          /* @__PURE__ */ jsxs4("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs4("li", {
                children: [
                  /* @__PURE__ */ jsx4("strong", {
                    children: "Manual invocation"
                  }),
                  " \u2013 A user or system calls the workflow via an API endpoint."
                ]
              }),
              /* @__PURE__ */ jsxs4("li", {
                children: [
                  /* @__PURE__ */ jsx4("strong", {
                    children: "Event-driven"
                  }),
                  " \u2013 The workflow starts automatically when a specific event occurs (e.g., a new order is created)."
                ]
              }),
              /* @__PURE__ */ jsxs4("li", {
                children: [
                  /* @__PURE__ */ jsx4("strong", {
                    children: "Scheduled"
                  }),
                  " \u2013 The workflow runs on a cron schedule (e.g., nightly batch processing)."
                ]
              }),
              /* @__PURE__ */ jsxs4("li", {
                children: [
                  /* @__PURE__ */ jsx4("strong", {
                    children: "Chained"
                  }),
                  " \u2013 One workflow can invoke another as a step."
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs4("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx4("h2", {
            className: "text-2xl font-bold",
            children: "Monitoring and versioning"
          }),
          /* @__PURE__ */ jsx4("p", {
            className: "text-muted-foreground",
            children: "ContractSpec automatically instruments workflows with telemetry. You can view:"
          }),
          /* @__PURE__ */ jsxs4("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx4("li", {
                children: "Real-time execution status for each step"
              }),
              /* @__PURE__ */ jsx4("li", {
                children: "Historical run data and success/failure rates"
              }),
              /* @__PURE__ */ jsx4("li", {
                children: "Latency distributions and SLA compliance"
              }),
              /* @__PURE__ */ jsx4("li", {
                children: "Compensation events and retry attempts"
              })
            ]
          }),
          /* @__PURE__ */ jsx4("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__ */ jsxs4("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx4("h2", {
            className: "text-2xl font-bold",
            children: "Best practices"
          }),
          /* @__PURE__ */ jsxs4("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx4("li", {
                children: "Keep steps idempotent \u2013 they should be safe to retry without side effects."
              }),
              /* @__PURE__ */ jsx4("li", {
                children: "Define compensation for any step that modifies external state."
              }),
              /* @__PURE__ */ jsx4("li", {
                children: "Use meaningful step IDs that describe the operation."
              }),
              /* @__PURE__ */ jsx4("li", {
                children: "Set realistic SLAs and monitor them in production."
              }),
              /* @__PURE__ */ jsx4("li", {
                children: "Test failure scenarios locally before deploying."
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs4("div", {
        className: "flex items-center gap-4 pt-4",
        children: [
          /* @__PURE__ */ jsx4(Link4, {
            href: "/docs/specs/capabilities",
            className: "btn-ghost",
            children: "Previous: Capabilities"
          }),
          /* @__PURE__ */ jsxs4(Link4, {
            href: "/docs/safety",
            className: "btn-primary",
            children: [
              "Next: Safety Features ",
              /* @__PURE__ */ jsx4(ChevronRight4, {
                size: 16
              })
            ]
          })
        ]
      })
    ]
  });
}

// src/components/docs/specs/SpecsPolicyPage.tsx
import Link5 from "@contractspec/lib.ui-link";
import { ChevronRight as ChevronRight5 } from "lucide-react";
import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
function SpecsPolicyPage() {
  return /* @__PURE__ */ jsxs5("div", {
    className: "space-y-8",
    children: [
      /* @__PURE__ */ jsxs5("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx5("h1", {
            className: "text-4xl font-bold",
            children: "Policy"
          }),
          /* @__PURE__ */ jsxs5("p", {
            className: "text-muted-foreground",
            children: [
              "A ",
              /* @__PURE__ */ jsx5("strong", {
                children: "PolicySpec"
              }),
              " defines who can do what, when, and under what conditions. ContractSpec uses attribute-based access control (ABAC) to enforce policies across your entire application\u2014from API endpoints to UI components."
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs5("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx5("h2", {
            className: "text-2xl font-bold",
            children: "Why policies matter"
          }),
          /* @__PURE__ */ jsx5("p", {
            className: "text-muted-foreground",
            children: "Traditional access control relies on roles (RBAC), which can become unwieldy as applications grow. ABAC is more flexible\u2014it evaluates policies based on attributes of the user, resource, action, and context."
          }),
          /* @__PURE__ */ jsxs5("p", {
            className: "text-muted-foreground",
            children: [
              "ContractSpec's policy engine ensures that access control is consistent across all surfaces. You don't have to remember to add authorization checks in every API endpoint or UI component\u2014the",
              " ",
              /* @__PURE__ */ jsx5(Link5, {
                href: "/docs/safety/pdp",
                className: "text-violet-400 hover:text-violet-300",
                children: "Policy Decision Point"
              }),
              " ",
              "enforces policies automatically."
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs5("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx5("h2", {
            className: "text-2xl font-bold",
            children: "Policy structure"
          }),
          /* @__PURE__ */ jsx5("p", {
            className: "text-muted-foreground",
            children: "A PolicySpec contains one or more rules. Each rule has:"
          }),
          /* @__PURE__ */ jsxs5("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs5("li", {
                children: [
                  /* @__PURE__ */ jsx5("strong", {
                    children: "Effect"
                  }),
                  " \u2013 PERMIT, DENY, or REDACT"
                ]
              }),
              /* @__PURE__ */ jsxs5("li", {
                children: [
                  /* @__PURE__ */ jsx5("strong", {
                    children: "Condition"
                  }),
                  " \u2013 A boolean expression that determines when the rule applies"
                ]
              }),
              /* @__PURE__ */ jsxs5("li", {
                children: [
                  /* @__PURE__ */ jsx5("strong", {
                    children: "Scope"
                  }),
                  " \u2013 Which resources, actions, or fields the rule applies to"
                ]
              }),
              /* @__PURE__ */ jsxs5("li", {
                children: [
                  /* @__PURE__ */ jsx5("strong", {
                    children: "Priority"
                  }),
                  " \u2013 Rules are evaluated in priority order; the first matching rule wins"
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs5("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx5("h2", {
            className: "text-2xl font-bold",
            children: "Example PolicySpec"
          }),
          /* @__PURE__ */ jsx5("p", {
            className: "text-muted-foreground",
            children: "Here's a policy that controls access to customer data in TypeScript:"
          }),
          /* @__PURE__ */ jsx5("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx5("pre", {
              children: `import { definePolicy } from '@contractspec/lib.contracts-spec';

export const CustomerDataAccess = definePolicy({
  meta: {
    key: 'customer.data.access',
    version: '1.0.0',
  },
  rules: [
    {
      id: 'admin-full-access',
      priority: 100,
      effect: 'PERMIT',
      condition: (ctx) => ctx.user.role === 'admin',
      scope: {
        resources: ['customer'],
        actions: ['read', 'write', 'delete'],
      },
    },
    {
      id: 'sales-read-assigned',
      priority: 200,
      effect: 'PERMIT',
      condition: (ctx) => 
        ctx.user.role === 'sales' && 
        ctx.resource.assignedTo === ctx.user.id,
      scope: {
        resources: ['customer'],
        actions: ['read', 'write'],
      },
    },
    {
      id: 'support-read-redacted',
      priority: 300,
      effect: 'REDACT',
      condition: (ctx) => ctx.user.role === 'support',
      scope: {
        resources: ['customer'],
        actions: ['read'],
      },
      redactFields: ['creditCard', 'ssn', 'bankAccount'],
    },
  ],
});`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs5("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx5("h2", {
            className: "text-2xl font-bold",
            children: "Attributes"
          }),
          /* @__PURE__ */ jsx5("p", {
            className: "text-muted-foreground",
            children: "Policy conditions can reference attributes from four categories:"
          }),
          /* @__PURE__ */ jsxs5("div", {
            className: "space-y-3",
            children: [
              /* @__PURE__ */ jsxs5("div", {
                children: [
                  /* @__PURE__ */ jsx5("h3", {
                    className: "text-lg font-semibold",
                    children: "User attributes"
                  }),
                  /* @__PURE__ */ jsxs5("p", {
                    className: "text-muted-foreground",
                    children: [
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "user.id"
                      }),
                      ",",
                      " ",
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "user.role"
                      }),
                      ",",
                      " ",
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "user.groups"
                      }),
                      ",",
                      " ",
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "user.department"
                      }),
                      ", custom attributes"
                    ]
                  })
                ]
              }),
              /* @__PURE__ */ jsxs5("div", {
                children: [
                  /* @__PURE__ */ jsx5("h3", {
                    className: "text-lg font-semibold",
                    children: "Resource attributes"
                  }),
                  /* @__PURE__ */ jsxs5("p", {
                    className: "text-muted-foreground",
                    children: [
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "resource.type"
                      }),
                      ",",
                      " ",
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "resource.owner"
                      }),
                      ",",
                      " ",
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "resource.sensitivity"
                      }),
                      ", custom attributes"
                    ]
                  })
                ]
              }),
              /* @__PURE__ */ jsxs5("div", {
                children: [
                  /* @__PURE__ */ jsx5("h3", {
                    className: "text-lg font-semibold",
                    children: "Action attributes"
                  }),
                  /* @__PURE__ */ jsxs5("p", {
                    className: "text-muted-foreground",
                    children: [
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "action"
                      }),
                      " ",
                      "(read, write, delete, execute, export, etc.)"
                    ]
                  })
                ]
              }),
              /* @__PURE__ */ jsxs5("div", {
                children: [
                  /* @__PURE__ */ jsx5("h3", {
                    className: "text-lg font-semibold",
                    children: "Context attributes"
                  }),
                  /* @__PURE__ */ jsxs5("p", {
                    className: "text-muted-foreground",
                    children: [
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "time.hour"
                      }),
                      ",",
                      " ",
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "time.dayOfWeek"
                      }),
                      ",",
                      " ",
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "request.ipAddress"
                      }),
                      ",",
                      " ",
                      /* @__PURE__ */ jsx5("code", {
                        className: "bg-background/50 rounded px-2 py-1",
                        children: "request.userAgent"
                      })
                    ]
                  })
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs5("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx5("h2", {
            className: "text-2xl font-bold",
            children: "Data classification"
          }),
          /* @__PURE__ */ jsxs5("p", {
            className: "text-muted-foreground",
            children: [
              "You can tag fields with sensitivity levels in your",
              " ",
              /* @__PURE__ */ jsx5(Link5, {
                href: "/docs/specs/capabilities",
                className: "text-violet-400 hover:text-violet-300",
                children: "CapabilitySpecs"
              }),
              " ",
              "and",
              " ",
              /* @__PURE__ */ jsx5(Link5, {
                href: "/docs/specs/dataviews",
                className: "text-violet-400 hover:text-violet-300",
                children: "DataViewSpecs"
              }),
              ":"
            ]
          }),
          /* @__PURE__ */ jsx5("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx5("pre", {
              children: `fields:
  - name: email
    type: string
    sensitivity: PII
  - name: creditCard
    type: string
    sensitivity: PII
    encrypted: true
  - name: diagnosis
    type: string
    sensitivity: PHI
  - name: salary
    type: number
    sensitivity: confidential`
            })
          }),
          /* @__PURE__ */ jsx5("p", {
            className: "text-muted-foreground",
            children: 'Policies can then reference these tags to enforce blanket rules like "support staff cannot see PII" or "PHI can only be accessed from approved IP addresses."'
          })
        ]
      }),
      /* @__PURE__ */ jsxs5("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx5("h2", {
            className: "text-2xl font-bold",
            children: "Testing policies"
          }),
          /* @__PURE__ */ jsx5("p", {
            className: "text-muted-foreground",
            children: "ContractSpec provides tools for testing policies before deployment:"
          }),
          /* @__PURE__ */ jsxs5("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs5("li", {
                children: [
                  /* @__PURE__ */ jsx5("strong", {
                    children: "Policy simulator"
                  }),
                  " \u2013 Test how policies evaluate for different users and scenarios"
                ]
              }),
              /* @__PURE__ */ jsxs5("li", {
                children: [
                  /* @__PURE__ */ jsx5("strong", {
                    children: "Coverage analysis"
                  }),
                  " \u2013 Identify resources or actions that aren't covered by any policy"
                ]
              }),
              /* @__PURE__ */ jsxs5("li", {
                children: [
                  /* @__PURE__ */ jsx5("strong", {
                    children: "Conflict detection"
                  }),
                  " \u2013 Find rules that might conflict or produce unexpected results"
                ]
              }),
              /* @__PURE__ */ jsxs5("li", {
                children: [
                  /* @__PURE__ */ jsx5("strong", {
                    children: "Audit mode"
                  }),
                  " \u2013 Run policies in audit-only mode to see what would be blocked without actually blocking it"
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs5("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx5("h2", {
            className: "text-2xl font-bold",
            children: "Best practices"
          }),
          /* @__PURE__ */ jsxs5("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx5("li", {
                children: "Start with a deny-by-default policy\u2014explicitly permit what should be allowed."
              }),
              /* @__PURE__ */ jsx5("li", {
                children: "Use clear, descriptive rule IDs that explain what the rule does."
              }),
              /* @__PURE__ */ jsx5("li", {
                children: "Set priorities carefully to ensure rules are evaluated in the right order."
              }),
              /* @__PURE__ */ jsx5("li", {
                children: "Test policies thoroughly with realistic user scenarios before deploying."
              }),
              /* @__PURE__ */ jsxs5("li", {
                children: [
                  "Monitor policy decisions in production using",
                  " ",
                  /* @__PURE__ */ jsx5(Link5, {
                    href: "/docs/safety/auditing",
                    className: "text-violet-400 hover:text-violet-300",
                    children: "audit logs"
                  }),
                  "."
                ]
              }),
              /* @__PURE__ */ jsx5("li", {
                children: "Review and update policies regularly as your application and requirements evolve."
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs5("div", {
        className: "flex items-center gap-4 pt-4",
        children: [
          /* @__PURE__ */ jsx5(Link5, {
            href: "/docs/specs/workflows",
            className: "btn-ghost",
            children: "Previous: Workflows"
          }),
          /* @__PURE__ */ jsxs5(Link5, {
            href: "/docs/specs/overlays",
            className: "btn-primary",
            children: [
              "Next: Overlays ",
              /* @__PURE__ */ jsx5(ChevronRight5, {
                size: 16
              })
            ]
          })
        ]
      })
    ]
  });
}

// src/components/docs/specs/SpecsOverlaysPage.tsx
import Link6 from "@contractspec/lib.ui-link";
import { ChevronRight as ChevronRight6 } from "lucide-react";
import { jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
function SpecsOverlaysPage() {
  return /* @__PURE__ */ jsxs6("div", {
    className: "space-y-8",
    children: [
      /* @__PURE__ */ jsxs6("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx6("h1", {
            className: "text-4xl font-bold",
            children: "Overlays"
          }),
          /* @__PURE__ */ jsxs6("p", {
            className: "text-muted-foreground",
            children: [
              "An ",
              /* @__PURE__ */ jsx6("strong", {
                children: "OverlaySpec"
              }),
              " allows tenants or users to customize UI layouts and field visibility without modifying the underlying application code. Overlays are cryptographically signed to ensure they respect policy boundaries and cannot introduce security vulnerabilities."
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs6("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx6("h2", {
            className: "text-2xl font-bold",
            children: "Why overlays matter"
          }),
          /* @__PURE__ */ jsx6("p", {
            className: "text-muted-foreground",
            children: "Different users have different needs. A power user might want to see all available fields and actions, while a casual user prefers a simplified interface. A tenant in a multi-tenant application might want to brand the UI or hide features they don't use."
          }),
          /* @__PURE__ */ jsx6("p", {
            className: "text-muted-foreground",
            children: "Traditional approaches require either building multiple UIs or adding complex configuration logic throughout the codebase. OverlaySpecs provide a safer, more maintainable solution: users can customize their experience, but only within the bounds allowed by the underlying specs and policies."
          })
        ]
      }),
      /* @__PURE__ */ jsxs6("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx6("h2", {
            className: "text-2xl font-bold",
            children: "What overlays can do"
          }),
          /* @__PURE__ */ jsxs6("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Hide or show fields"
                  }),
                  " \u2013 Remove fields from forms or detail views (but only if the user has permission to see them in the first place)"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Reorder fields"
                  }),
                  " \u2013 Change the order in which fields appear"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Rename labels"
                  }),
                  " \u2013 Use different terminology that's more familiar to the user"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Change layouts"
                  }),
                  " \u2013 Switch between list, grid, or card views"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Add help text"
                  }),
                  " \u2013 Provide context-specific guidance"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Set default values"
                  }),
                  " \u2013 Pre-fill forms with tenant-specific defaults"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Apply branding"
                  }),
                  " \u2013 Customize colors, logos, and styling (within approved themes)"
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs6("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx6("h2", {
            className: "text-2xl font-bold",
            children: "Example OverlaySpec"
          }),
          /* @__PURE__ */ jsx6("p", {
            className: "text-muted-foreground",
            children: "Here's an overlay that customizes an order form:"
          }),
          /* @__PURE__ */ jsx6("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx6("pre", {
              children: `overlayId: acme-order-form
version: '1.0.0'.0.0
appliesTo:
  capability: createOrder
  tenantId: acme-corp
  
modifications:
  - type: hideField
    field: internalNotes
    reason: "ACME doesn't use internal notes"
    
  - type: renameLabel
    field: customerReference
    newLabel: "PO Number"
    
  - type: reorderFields
    fields:
      - customerReference
      - items
      - shippingAddress
      - billingAddress
      - paymentMethod
      
  - type: setDefault
    field: paymentMethod
    value: "net30"
    
  - type: addHelpText
    field: customerReference
    text: "Enter your purchase order number from your procurement system"
    
  - type: makeRequired
    field: customerReference
    
signature:
  algorithm: EdDSA
  publicKey: "acme-corp-overlay-key"
  signature: "base64-encoded-signature"`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs6("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx6("h2", {
            className: "text-2xl font-bold",
            children: "Safety guarantees"
          }),
          /* @__PURE__ */ jsx6("p", {
            className: "text-muted-foreground",
            children: "Overlays are powerful, but they must not compromise security or data integrity. ContractSpec enforces several guarantees:"
          }),
          /* @__PURE__ */ jsxs6("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Overlays cannot grant new permissions"
                  }),
                  " \u2013 They can only hide or rearrange what the user is already allowed to see"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Overlays cannot bypass validation"
                  }),
                  " \u2013 Field types, constraints, and business rules from the underlying spec still apply"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Overlays must be signed"
                  }),
                  " \u2013 Only authorized parties (typically tenant admins) can create overlays"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Overlays are versioned"
                  }),
                  " \u2013 Changes to overlays are tracked and can be rolled back"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Overlays are audited"
                  }),
                  " \u2013 Every overlay application is logged"
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs6("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx6("h2", {
            className: "text-2xl font-bold",
            children: "Creating overlays"
          }),
          /* @__PURE__ */ jsx6("p", {
            className: "text-muted-foreground",
            children: "Overlays can be created through:"
          }),
          /* @__PURE__ */ jsxs6("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Visual editor"
                  }),
                  " \u2013 A drag-and-drop interface for non-technical users"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "TypeScript/JSON"
                  }),
                  " \u2013 For developers who prefer code"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "API"
                  }),
                  " \u2013 Programmatically create overlays for automation"
                ]
              })
            ]
          }),
          /* @__PURE__ */ jsx6("p", {
            className: "text-muted-foreground",
            children: "Once created, overlays must be signed using a private key. The corresponding public key is registered with ContractSpec, which verifies the signature before applying the overlay."
          }),
          /* @__PURE__ */ jsxs6("p", {
            className: "text-muted-foreground",
            children: [
              "See",
              " ",
              /* @__PURE__ */ jsx6(Link6, {
                href: "/docs/libraries/overlay-engine",
                className: "text-violet-400 underline",
                children: "Overlay Engine docs"
              }),
              " ",
              "and the",
              " ",
              /* @__PURE__ */ jsx6(Link6, {
                href: "/docs/advanced/overlay-editor",
                className: "text-violet-400 underline",
                children: "Overlay Editor guide"
              }),
              " ",
              "for end-to-end workflows."
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs6("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx6("h2", {
            className: "text-2xl font-bold",
            children: "Overlay scope"
          }),
          /* @__PURE__ */ jsx6("p", {
            className: "text-muted-foreground",
            children: "Overlays can be scoped to:"
          }),
          /* @__PURE__ */ jsxs6("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Tenant"
                  }),
                  " \u2013 All users in a tenant see the same overlay"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "User"
                  }),
                  " \u2013 Individual users can have personal overlays"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Role"
                  }),
                  " \u2013 All users with a specific role see the overlay"
                ]
              }),
              /* @__PURE__ */ jsxs6("li", {
                children: [
                  /* @__PURE__ */ jsx6("strong", {
                    children: "Device"
                  }),
                  " \u2013 Different overlays for mobile vs desktop"
                ]
              })
            ]
          }),
          /* @__PURE__ */ jsx6("p", {
            className: "text-muted-foreground",
            children: "If multiple overlays apply to the same user, they are merged in order of specificity (user overlays override role overlays, which override tenant overlays)."
          })
        ]
      }),
      /* @__PURE__ */ jsxs6("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx6("h2", {
            className: "text-2xl font-bold",
            children: "Best practices"
          }),
          /* @__PURE__ */ jsxs6("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx6("li", {
                children: "Start with the default UI and only create overlays when users request specific changes."
              }),
              /* @__PURE__ */ jsx6("li", {
                children: "Document why each overlay modification was made\u2014this helps when reviewing or updating overlays."
              }),
              /* @__PURE__ */ jsx6("li", {
                children: "Test overlays thoroughly to ensure they don't break workflows or confuse users."
              }),
              /* @__PURE__ */ jsx6("li", {
                children: "Use tenant-level overlays for organizational customizations and user-level overlays for personal preferences."
              }),
              /* @__PURE__ */ jsx6("li", {
                children: "Regularly review overlays to remove ones that are no longer needed."
              }),
              /* @__PURE__ */ jsx6("li", {
                children: "Protect overlay signing keys carefully\u2014they control what customizations are allowed."
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs6("div", {
        className: "flex items-center gap-4 pt-4",
        children: [
          /* @__PURE__ */ jsx6(Link6, {
            href: "/docs/specs/policy",
            className: "btn-ghost",
            children: "Previous: Policy"
          }),
          /* @__PURE__ */ jsxs6(Link6, {
            href: "/docs/safety",
            className: "btn-primary",
            children: [
              "Next: Safety ",
              /* @__PURE__ */ jsx6(ChevronRight6, {
                size: 16
              })
            ]
          })
        ]
      })
    ]
  });
}
export {
  SpecsWorkflowsPage,
  SpecsPolicyPage,
  SpecsOverviewPage,
  SpecsOverlaysPage,
  SpecsDataViewsPage,
  SpecsCapabilitiesPage
};
