@contractspec/bundle.library 0.0.0-canary-20260206014742

package/dist/components/docs/specs/SpecsPolicyPage.js

@@ -0,0 +1,367 @@
+import { ChevronRight } from "lucide-react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import Link from "@contractspec/lib.ui-link";
+
+//#region src/components/docs/specs/SpecsPolicyPage.tsx
+function SpecsPolicyPage() {
+	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: "Policy"
+				}), /* @__PURE__ */ jsxs("p", {
+					className: "text-muted-foreground",
+					children: [
+						"A ",
+						/* @__PURE__ */ jsx("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—from API endpoints to UI components."
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Why policies matter"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Traditional access control relies on roles (RBAC), which can become unwieldy as applications grow. ABAC is more flexible—it evaluates policies based on attributes of the user, resource, action, and context."
+					}),
+					/* @__PURE__ */ jsxs("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—the",
+							" ",
+							/* @__PURE__ */ jsx(Link, {
+								href: "/docs/safety/pdp",
+								className: "text-violet-400 hover:text-violet-300",
+								children: "Policy Decision Point"
+							}),
+							" ",
+							"enforces policies automatically."
+						]
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Policy structure"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "A PolicySpec contains one or more rules. Each rule has:"
+					}),
+					/* @__PURE__ */ jsxs("ul", {
+						className: "text-muted-foreground list-inside list-disc space-y-2",
+						children: [
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Effect" }), " – PERMIT, DENY, or REDACT"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Condition" }), " – A boolean expression that determines when the rule applies"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Scope" }), " – Which resources, actions, or fields the rule applies to"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Priority" }), " – Rules are evaluated in priority order; the first matching rule wins"] })
+						]
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Example PolicySpec"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Here's a policy that controls access to customer data 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 { definePolicy } from '@contractspec/lib.contracts';
+
+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__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Attributes"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "Policy conditions can reference attributes from four categories:"
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h3", {
+								className: "text-lg font-semibold",
+								children: "User attributes"
+							}), /* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground",
+								children: [
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "user.id"
+									}),
+									",",
+									" ",
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "user.role"
+									}),
+									",",
+									" ",
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "user.groups"
+									}),
+									",",
+									" ",
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "user.department"
+									}),
+									", custom attributes"
+								]
+							})] }),
+							/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h3", {
+								className: "text-lg font-semibold",
+								children: "Resource attributes"
+							}), /* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground",
+								children: [
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "resource.type"
+									}),
+									",",
+									" ",
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "resource.owner"
+									}),
+									",",
+									" ",
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "resource.sensitivity"
+									}),
+									", custom attributes"
+								]
+							})] }),
+							/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h3", {
+								className: "text-lg font-semibold",
+								children: "Action attributes"
+							}), /* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground",
+								children: [
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "action"
+									}),
+									" ",
+									"(read, write, delete, execute, export, etc.)"
+								]
+							})] }),
+							/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h3", {
+								className: "text-lg font-semibold",
+								children: "Context attributes"
+							}), /* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground",
+								children: [
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "time.hour"
+									}),
+									",",
+									" ",
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "time.dayOfWeek"
+									}),
+									",",
+									" ",
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "request.ipAddress"
+									}),
+									",",
+									" ",
+									/* @__PURE__ */ jsx("code", {
+										className: "bg-background/50 rounded px-2 py-1",
+										children: "request.userAgent"
+									})
+								]
+							})] })
+						]
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Data classification"
+					}),
+					/* @__PURE__ */ jsxs("p", {
+						className: "text-muted-foreground",
+						children: [
+							"You can tag fields with sensitivity levels in your",
+							" ",
+							/* @__PURE__ */ jsx(Link, {
+								href: "/docs/specs/capabilities",
+								className: "text-violet-400 hover:text-violet-300",
+								children: "CapabilitySpecs"
+							}),
+							" ",
+							"and",
+							" ",
+							/* @__PURE__ */ jsx(Link, {
+								href: "/docs/specs/dataviews",
+								className: "text-violet-400 hover:text-violet-300",
+								children: "DataViewSpecs"
+							}),
+							":"
+						]
+					}),
+					/* @__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: `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__ */ jsx("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__ */ jsxs("div", {
+				className: "space-y-4",
+				children: [
+					/* @__PURE__ */ jsx("h2", {
+						className: "text-2xl font-bold",
+						children: "Testing policies"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "text-muted-foreground",
+						children: "ContractSpec provides tools for testing policies before deployment:"
+					}),
+					/* @__PURE__ */ jsxs("ul", {
+						className: "text-muted-foreground list-inside list-disc space-y-2",
+						children: [
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Policy simulator" }), " – Test how policies evaluate for different users and scenarios"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Coverage analysis" }), " – Identify resources or actions that aren't covered by any policy"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Conflict detection" }), " – Find rules that might conflict or produce unexpected results"] }),
+							/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Audit mode" }), " – Run policies in audit-only mode to see what would be blocked without actually blocking it"] })
+						]
+					})
+				]
+			}),
+			/* @__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: "Start with a deny-by-default policy—explicitly permit what should be allowed." }),
+						/* @__PURE__ */ jsx("li", { children: "Use clear, descriptive rule IDs that explain what the rule does." }),
+						/* @__PURE__ */ jsx("li", { children: "Set priorities carefully to ensure rules are evaluated in the right order." }),
+						/* @__PURE__ */ jsx("li", { children: "Test policies thoroughly with realistic user scenarios before deploying." }),
+						/* @__PURE__ */ jsxs("li", { children: [
+							"Monitor policy decisions in production using",
+							" ",
+							/* @__PURE__ */ jsx(Link, {
+								href: "/docs/safety/auditing",
+								className: "text-violet-400 hover:text-violet-300",
+								children: "audit logs"
+							}),
+							"."
+						] }),
+						/* @__PURE__ */ jsx("li", { children: "Review and update policies regularly as your application and requirements evolve." })
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-4 pt-4",
+				children: [/* @__PURE__ */ jsx(Link, {
+					href: "/docs/specs/workflows",
+					className: "btn-ghost",
+					children: "Previous: Workflows"
+				}), /* @__PURE__ */ jsxs(Link, {
+					href: "/docs/specs/overlays",
+					className: "btn-primary",
+					children: ["Next: Overlays ", /* @__PURE__ */ jsx(ChevronRight, { size: 16 })]
+				})]
+			})
+		]
+	});
+}
+
+//#endregion
+export { SpecsPolicyPage };
+//# sourceMappingURL=SpecsPolicyPage.js.map

package/dist/components/docs/specs/SpecsPolicyPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpecsPolicyPage.js","names":[],"sources":["../../../../src/components/docs/specs/SpecsPolicyPage.tsx"],"sourcesContent":["import Link from '@contractspec/lib.ui-link';\nimport { ChevronRight } from 'lucide-react';\n\n// export const metadata = {\n//   title: 'Policy: ContractSpec Docs',\n//   description:\n//     'Learn how to define attribute-based access control and data protection policies in ContractSpec.',\n// };\n\nexport function SpecsPolicyPage() {\n  return (\n    <div className=\"space-y-8\">\n      <div className=\"space-y-4\">\n        <h1 className=\"text-4xl font-bold\">Policy</h1>\n        <p className=\"text-muted-foreground\">\n          A <strong>PolicySpec</strong> defines who can do what, when, and under\n          what conditions. ContractSpec uses attribute-based access control\n          (ABAC) to enforce policies across your entire application—from API\n          endpoints to UI components.\n        </p>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Why policies matter</h2>\n        <p className=\"text-muted-foreground\">\n          Traditional access control relies on roles (RBAC), which can become\n          unwieldy as applications grow. ABAC is more flexible—it evaluates\n          policies based on attributes of the user, resource, action, and\n          context.\n        </p>\n        <p className=\"text-muted-foreground\">\n          ContractSpec's policy engine ensures that access control is consistent\n          across all surfaces. You don't have to remember to add authorization\n          checks in every API endpoint or UI component—the{' '}\n          <Link\n            href=\"/docs/safety/pdp\"\n            className=\"text-violet-400 hover:text-violet-300\"\n          >\n            Policy Decision Point\n          </Link>{' '}\n          enforces policies automatically.\n        </p>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Policy structure</h2>\n        <p className=\"text-muted-foreground\">\n          A PolicySpec contains one or more rules. Each rule has:\n        </p>\n        <ul className=\"text-muted-foreground list-inside list-disc space-y-2\">\n          <li>\n            <strong>Effect</strong> – PERMIT, DENY, or REDACT\n          </li>\n          <li>\n            <strong>Condition</strong> – A boolean expression that determines\n            when the rule applies\n          </li>\n          <li>\n            <strong>Scope</strong> – Which resources, actions, or fields the\n            rule applies to\n          </li>\n          <li>\n            <strong>Priority</strong> – Rules are evaluated in priority order;\n            the first matching rule wins\n          </li>\n        </ul>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Example PolicySpec</h2>\n        <p className=\"text-muted-foreground\">\n          Here's a policy that controls access to customer data in TypeScript:\n        </p>\n        <div className=\"bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm\">\n          <pre>{`import { definePolicy } from '@contractspec/lib.contracts';\n\nexport const CustomerDataAccess = definePolicy({\n  meta: {\n    key: 'customer.data.access',\n    version: '1.0.0',\n  },\n  rules: [\n    {\n      id: 'admin-full-access',\n      priority: 100,\n      effect: 'PERMIT',\n      condition: (ctx) => ctx.user.role === 'admin',\n      scope: {\n        resources: ['customer'],\n        actions: ['read', 'write', 'delete'],\n      },\n    },\n    {\n      id: 'sales-read-assigned',\n      priority: 200,\n      effect: 'PERMIT',\n      condition: (ctx) => \n        ctx.user.role === 'sales' && \n        ctx.resource.assignedTo === ctx.user.id,\n      scope: {\n        resources: ['customer'],\n        actions: ['read', 'write'],\n      },\n    },\n    {\n      id: 'support-read-redacted',\n      priority: 300,\n      effect: 'REDACT',\n      condition: (ctx) => ctx.user.role === 'support',\n      scope: {\n        resources: ['customer'],\n        actions: ['read'],\n      },\n      redactFields: ['creditCard', 'ssn', 'bankAccount'],\n    },\n  ],\n});`}</pre>\n        </div>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Attributes</h2>\n        <p className=\"text-muted-foreground\">\n          Policy conditions can reference attributes from four categories:\n        </p>\n        <div className=\"space-y-3\">\n          <div>\n            <h3 className=\"text-lg font-semibold\">User attributes</h3>\n            <p className=\"text-muted-foreground\">\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                user.id\n              </code>\n              ,{' '}\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                user.role\n              </code>\n              ,{' '}\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                user.groups\n              </code>\n              ,{' '}\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                user.department\n              </code>\n              , custom attributes\n            </p>\n          </div>\n          <div>\n            <h3 className=\"text-lg font-semibold\">Resource attributes</h3>\n            <p className=\"text-muted-foreground\">\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                resource.type\n              </code>\n              ,{' '}\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                resource.owner\n              </code>\n              ,{' '}\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                resource.sensitivity\n              </code>\n              , custom attributes\n            </p>\n          </div>\n          <div>\n            <h3 className=\"text-lg font-semibold\">Action attributes</h3>\n            <p className=\"text-muted-foreground\">\n              <code className=\"bg-background/50 rounded px-2 py-1\">action</code>{' '}\n              (read, write, delete, execute, export, etc.)\n            </p>\n          </div>\n          <div>\n            <h3 className=\"text-lg font-semibold\">Context attributes</h3>\n            <p className=\"text-muted-foreground\">\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                time.hour\n              </code>\n              ,{' '}\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                time.dayOfWeek\n              </code>\n              ,{' '}\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                request.ipAddress\n              </code>\n              ,{' '}\n              <code className=\"bg-background/50 rounded px-2 py-1\">\n                request.userAgent\n              </code>\n            </p>\n          </div>\n        </div>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Data classification</h2>\n        <p className=\"text-muted-foreground\">\n          You can tag fields with sensitivity levels in your{' '}\n          <Link\n            href=\"/docs/specs/capabilities\"\n            className=\"text-violet-400 hover:text-violet-300\"\n          >\n            CapabilitySpecs\n          </Link>{' '}\n          and{' '}\n          <Link\n            href=\"/docs/specs/dataviews\"\n            className=\"text-violet-400 hover:text-violet-300\"\n          >\n            DataViewSpecs\n          </Link>\n          :\n        </p>\n        <div className=\"bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm\">\n          <pre>{`fields:\n  - name: email\n    type: string\n    sensitivity: PII\n  - name: creditCard\n    type: string\n    sensitivity: PII\n    encrypted: true\n  - name: diagnosis\n    type: string\n    sensitivity: PHI\n  - name: salary\n    type: number\n    sensitivity: confidential`}</pre>\n        </div>\n        <p className=\"text-muted-foreground\">\n          Policies can then reference these tags to enforce blanket rules like\n          \"support staff cannot see PII\" or \"PHI can only be accessed from\n          approved IP addresses.\"\n        </p>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Testing policies</h2>\n        <p className=\"text-muted-foreground\">\n          ContractSpec provides tools for testing policies before deployment:\n        </p>\n        <ul className=\"text-muted-foreground list-inside list-disc space-y-2\">\n          <li>\n            <strong>Policy simulator</strong> – Test how policies evaluate for\n            different users and scenarios\n          </li>\n          <li>\n            <strong>Coverage analysis</strong> – Identify resources or actions\n            that aren't covered by any policy\n          </li>\n          <li>\n            <strong>Conflict detection</strong> – Find rules that might conflict\n            or produce unexpected results\n          </li>\n          <li>\n            <strong>Audit mode</strong> – Run policies in audit-only mode to see\n            what would be blocked without actually blocking it\n          </li>\n        </ul>\n      </div>\n\n      <div className=\"space-y-4\">\n        <h2 className=\"text-2xl font-bold\">Best practices</h2>\n        <ul className=\"text-muted-foreground list-inside list-disc space-y-2\">\n          <li>\n            Start with a deny-by-default policy—explicitly permit what should be\n            allowed.\n          </li>\n          <li>\n            Use clear, descriptive rule IDs that explain what the rule does.\n          </li>\n          <li>\n            Set priorities carefully to ensure rules are evaluated in the right\n            order.\n          </li>\n          <li>\n            Test policies thoroughly with realistic user scenarios before\n            deploying.\n          </li>\n          <li>\n            Monitor policy decisions in production using{' '}\n            <Link\n              href=\"/docs/safety/auditing\"\n              className=\"text-violet-400 hover:text-violet-300\"\n            >\n              audit logs\n            </Link>\n            .\n          </li>\n          <li>\n            Review and update policies regularly as your application and\n            requirements evolve.\n          </li>\n        </ul>\n      </div>\n\n      <div className=\"flex items-center gap-4 pt-4\">\n        <Link href=\"/docs/specs/workflows\" className=\"btn-ghost\">\n          Previous: Workflows\n        </Link>\n        <Link href=\"/docs/specs/overlays\" className=\"btn-primary\">\n          Next: Overlays <ChevronRight size={16} />\n        </Link>\n      </div>\n    </div>\n  );\n}\n"],"mappings":"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"}

package/dist/components/docs/specs/SpecsWorkflowsPage.d.ts

@@ -0,0 +1,7 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/docs/specs/SpecsWorkflowsPage.d.ts
+declare function SpecsWorkflowsPage(): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { SpecsWorkflowsPage };
+//# sourceMappingURL=SpecsWorkflowsPage.d.ts.map

package/dist/components/docs/specs/SpecsWorkflowsPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpecsWorkflowsPage.d.ts","names":[],"sources":["../../../../src/components/docs/specs/SpecsWorkflowsPage.tsx"],"mappings":";;;iBASgB,kBAAA,CAAA,GAAkB,kBAAA,CAAA,GAAA,CAAA,OAAA"}

package/dist/components/docs/specs/SpecsWorkflowsPage.js

@@ -0,0 +1,259 @@
+import { ChevronRight } from "lucide-react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import Link from "@contractspec/lib.ui-link";
+
+//#region src/components/docs/specs/SpecsWorkflowsPage.tsx
+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';
+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 })]
+				})]
+			})
+		]
+	});
+}
+
+//#endregion
+export { SpecsWorkflowsPage };
+//# sourceMappingURL=SpecsWorkflowsPage.js.map