@contractspec/bundle.library 3.9.4 → 3.9.6

package/.turbo/turbo-build.log

@@ -2,7 +2,7 @@ $ contractspec-bun-build prebuild
 $ bun run build:bundle && bun run build:types
 $ contractspec-bun-build transpile
 [contractspec-bun-build] transpile target=bun root=src entries=319 noBundle=false
-Bundled 319 modules in 221ms
+Bundled 319 modules in 408ms
 
   application/context-storage/index.js                                                                     0.85 KB    (entry point)
   presentation/features/templates/types.js                                                                 8 bytes    (entry point)
@@ -289,11 +289,11 @@ Bundled 319 modules in 221ms
   components/docs/architecture/ArchitectureOverviewPage.js                                                 4.72 KB    (entry point)
   components/docs/comparison/ComparisonAutomationPlatformsPage.js                                          5.13 KB    (entry point)
   components/docs/comparison/ComparisonEnterprisePlatformsPage.js                                          4.98 KB    (entry point)
-  components/docs/advanced/index.js                                                                        26.36 KB   (entry point)
+  components/docs/advanced/index.js                                                                        26.44 KB   (entry point)
   components/docs/advanced/AdvancedMCPPage.js                                                              8.52 KB    (entry point)
   components/docs/advanced/AdvancedOverlayEditorPage.js                                                    2.0 KB     (entry point)
   components/docs/advanced/AdvancedRenderersPage.js                                                        2.83 KB    (entry point)
-  components/docs/advanced/AdvancedSpecExperimentsPage.js                                                  3.12 KB    (entry point)
+  components/docs/advanced/AdvancedSpecExperimentsPage.js                                                  3.19 KB    (entry point)
   components/docs/advanced/AdvancedTelemetryPage.js                                                        8.80 KB    (entry point)
   components/docs/advanced/AdvancedWorkflowMonitoringPage.js                                               2.18 KB    (entry point)
   components/docs/architecture/ArchitectureAppConfigPage.js                                                8.1 KB     (entry point)
@@ -325,7 +325,7 @@ Bundled 319 modules in 221ms
   application/mcp/contractsMcpResources.js                                                                 3.47 KB    (entry point)
 
 [contractspec-bun-build] transpile target=node root=src entries=319 noBundle=false
-Bundled 319 modules in 270ms
+Bundled 319 modules in 392ms
 
   application/context-storage/index.js                                                                     0.85 KB    (entry point)
   presentation/features/templates/types.js                                                                 0 KB       (entry point)
@@ -612,11 +612,11 @@ Bundled 319 modules in 270ms
   components/docs/architecture/ArchitectureOverviewPage.js                                                 4.71 KB    (entry point)
   components/docs/comparison/ComparisonAutomationPlatformsPage.js                                          5.11 KB    (entry point)
   components/docs/comparison/ComparisonEnterprisePlatformsPage.js                                          4.97 KB    (entry point)
-  components/docs/advanced/index.js                                                                        26.26 KB   (entry point)
+  components/docs/advanced/index.js                                                                        26.34 KB   (entry point)
   components/docs/advanced/AdvancedMCPPage.js                                                              8.51 KB    (entry point)
   components/docs/advanced/AdvancedOverlayEditorPage.js                                                    2.0 KB     (entry point)
   components/docs/advanced/AdvancedRenderersPage.js                                                        2.82 KB    (entry point)
-  components/docs/advanced/AdvancedSpecExperimentsPage.js                                                  3.1 KB     (entry point)
+  components/docs/advanced/AdvancedSpecExperimentsPage.js                                                  3.17 KB    (entry point)
   components/docs/advanced/AdvancedTelemetryPage.js                                                        8.72 KB    (entry point)
   components/docs/advanced/AdvancedWorkflowMonitoringPage.js                                               2.18 KB    (entry point)
   components/docs/architecture/ArchitectureAppConfigPage.js                                                8.1 KB     (entry point)
@@ -648,3 +648,6 @@ Bundled 319 modules in 270ms
   application/mcp/contractsMcpResources.js                                                                 3.46 KB    (entry point)
 
 $ contractspec-bun-build types
+$ contractspec-bun-build types
+$ contractspec-bun-build types
+$ contractspec-bun-build types

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @contractspec/bundle.library
 
+## 3.9.6
+
+### Patch Changes
+
+- chore: auto-bump internal dependents
+- Updated dependencies because of chore: auto-bump internal dependents
+- Updated dependencies because of Add Biome guardrails that keep JSX layout and text compatible with React and React Native.
+- Updated dependencies because of Add mobile-safe FormSpec layout helpers and scoped DataView filters.
+
+FormSpec authors can now use `responsiveFormColumns(...)` for explicit mobile-first column metadata without changing legacy numeric `layout.columns` behavior. DataView contracts can declare `filterScope.initial` and `filterScope.locked` filters so generic list/search contracts can be reused in context-restricted screens while keeping locked constraints out of user-editable URL state.
+
+- Updated dependencies because of Add OSS harness CLI verification with deterministic Playwright, optional agent-browser visual runs, auth profile refs, visual diff evidence, replay bundles, and core scenario success semantics.
+- Updated dependencies because of Complete the knowledge OSS surface with stricter guardrails and an easier runtime path.
+
+`@contractspec/lib.knowledge` now exposes a higher-level `KnowledgeRuntime` helper for the common ingest -> retrieve -> answer flow, adds per-query overrides on `KnowledgeQueryService`, and makes typed retrieval filters (`locale`, `category`) real rather than documentation-only. The access guard now enforces `automationWritable` and denies missing workflow/agent bindings when scoped allow-lists exist, which aligns runtime behavior with the contracts-spec knowledge semantics. The package also gains deeper regression coverage over previously untested public primitives.
+
+`@contractspec/example.knowledge-canon` now demonstrates a real `lib.knowledge` retrieval path instead of a placeholder TODO, so OSS consumers have a concrete example package they can reuse.
+
+- @contractspec/bundle.workspace@4.5.4
+- @contractspec/example.data-grid-showcase@3.8.18
+- @contractspec/lib.ai-providers@3.7.17
+- @contractspec/lib.content-gen@3.7.24
+- @contractspec/lib.contracts-integrations@3.8.16
+- @contractspec/lib.contracts-library@3.7.24
+- @contractspec/lib.contracts-runtime-server-graphql@3.8.3
+- @contractspec/lib.contracts-runtime-server-mcp@3.8.4
+- @contractspec/lib.contracts-runtime-server-rest@3.8.3
+- @contractspec/lib.example-shared-ui@7.0.3
+- @contractspec/lib.logger@3.7.17
+- @contractspec/lib.provider-ranking@0.7.17
+- @contractspec/lib.runtime-sandbox@3.0.3
+- @contractspec/lib.surface-runtime@0.5.24
+- @contractspec/lib.ui-link@3.7.19
+- @contractspec/module.context-storage@0.7.23
+- @contractspec/module.examples@4.0.3
+- @contractspec/lib.ui-kit-web@3.12.1
+- @contractspec/lib.design-system@4.1.0
+- @contractspec/lib.contracts-spec@5.7.0
+- @contractspec/lib.contracts-runtime-client-react@3.11.1
+- @contractspec/lib.knowledge@3.8.0
+
+## 3.9.5
+
+### Patch Changes
+
+- Migrate design-system platform implementation suffixes from `.mobile` to `.native`.
+  - Packages: @contractspec/lib.design-system (major), @contractspec/lib.presentation-runtime-core (patch), @contractspec/bundle.library (patch)
+  - Migration: Move direct design-system platform imports from `.mobile` to `.native`.
+  - Deprecations: Direct imports such as `@contractspec/lib.design-system/components/molecules/Tabs.mobile` have been replaced by `.native` subpaths.
+- Updated dependencies because of chore: auto-bump internal dependents
+- Updated dependencies because of Add Biome guardrails that keep JSX layout and text compatible with React and React Native.
+- Updated dependencies because of Add password-aware FormSpec rendering with current/new password manager hints and visibility toggles.
+- Updated dependencies because of Migrate design-system platform implementation suffixes from `.mobile` to `.native`.
+- Updated dependencies because of Harden published cross-platform UI packages around precise public subpath imports and closed native dist graphs.
+- Updated dependencies because of Use shared stack layout primitives in the web pagination component while preserving semantic pagination markup.
+- Updated dependencies because of Add a unified design-system Tabs primitive and migrate local tab consumers away from ui-kit leaf imports.
+  - @contractspec/bundle.workspace@4.5.3
+  - @contractspec/lib.ai-providers@3.7.16
+  - @contractspec/lib.content-gen@3.7.23
+  - @contractspec/lib.contracts-integrations@3.8.15
+  - @contractspec/lib.contracts-library@3.7.23
+  - @contractspec/lib.contracts-runtime-server-graphql@3.8.2
+  - @contractspec/lib.contracts-runtime-server-mcp@3.8.3
+  - @contractspec/lib.contracts-runtime-server-rest@3.8.2
+  - @contractspec/lib.example-shared-ui@7.0.2
+  - @contractspec/lib.knowledge@3.7.23
+  - @contractspec/lib.logger@3.7.16
+  - @contractspec/lib.provider-ranking@0.7.16
+  - @contractspec/lib.runtime-sandbox@3.0.2
+  - @contractspec/lib.surface-runtime@0.5.23
+  - @contractspec/lib.ui-link@3.7.18
+  - @contractspec/module.context-storage@0.7.22
+  - @contractspec/module.examples@4.0.2
+  - @contractspec/lib.ui-kit-web@3.12.0
+  - @contractspec/lib.design-system@4.0.0
+  - @contractspec/lib.contracts-spec@5.6.0
+  - @contractspec/lib.contracts-runtime-client-react@3.11.0
+  - @contractspec/example.data-grid-showcase@3.8.17
+  - @contractspec/lib.schema@3.7.14
+
 ## 3.9.4
 
 ### Patch Changes

package/dist/components/docs/advanced/AdvancedSpecExperimentsPage.js

@@ -1,5 +1,5 @@
 // @bun
-var o=Object.defineProperty;var l=(e)=>e;function n(e,r){this[e]=l.bind(null,r)}var c=(e,r)=>{for(var i in r)o(e,i,{get:r[i],enumerable:!0,configurable:!0,set:n.bind(r,i)})};var s=(e,r)=>()=>(e&&(r=e(e=0)),r);import{jsx as t,jsxs as a}from"react/jsx-runtime";function d(){return a("div",{className:"space-y-8",children:[a("div",{className:"space-y-4",children:[t("h1",{className:"font-bold text-4xl",children:"Spec Experiments"}),t("p",{className:"text-lg text-muted-foreground",children:"Run controlled experiments on ContractSpec operations, gradually shift traffic, and roll back automatically when guardrails trip."})]}),a("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"Define control + variants"}),t("pre",{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { SpecExperimentRegistry } from '@contractspec/lib.growth/spec-experiments';
+var D=Object.defineProperty;var E=(f)=>f;function F(f,q){this[f]=E.bind(null,q)}var J=(f,q)=>{for(var w in q)D(f,w,{get:q[w],enumerable:!0,configurable:!0,set:F.bind(q,w)})};var K=(f,q)=>()=>(f&&(q=f(f=0)),q);import{Code as z,H1 as G,H2 as A,H3 as I,P as B}from"@contractspec/lib.design-system/components/typography";import{jsx as k,jsxs as v}from"react/jsx-runtime";function N(){return v("div",{className:"space-y-8",children:[v("div",{className:"space-y-4",children:[k(G,{className:"font-bold text-4xl",children:"Spec Experiments"}),k(B,{className:"text-lg text-muted-foreground",children:"Run controlled experiments on ContractSpec operations, gradually shift traffic, and roll back automatically when guardrails trip."})]}),v("div",{className:"space-y-3",children:[k(A,{className:"font-bold text-2xl",children:"Define control + variants"}),k(z,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { SpecExperimentRegistry } from '@contractspec/lib.growth/spec-experiments';
 
 const registry = new SpecExperimentRegistry().register({
   target: { name: 'billing.createInvoice', version: 4 },
@@ -19,12 +19,12 @@ const registry = new SpecExperimentRegistry().register({
   ],
   rolloutStages: [0.01, 0.1, 0.5, 1],
   guardrails: { errorRateThreshold: 0.02, latencyP99ThresholdMs: 500 },
-});`})]}),a("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"Attach to runtime"}),t("pre",{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { createSpecVariantResolver } from '@contractspec/lib.growth/spec-experiments';
+});`})]}),v("div",{className:"space-y-3",children:[k(A,{className:"font-bold text-2xl",children:"Attach to runtime"}),k(z,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { createSpecVariantResolver } from '@contractspec/lib.growth/spec-experiments';
 
 adapterContext.specVariantResolver = createSpecVariantResolver({
   adapter,
   resolveUserId: (ctx) => ctx.userId ?? ctx.organizationId ?? 'anon',
-});`})]}),a("div",{className:"space-y-3",children:[t("h2",{className:"font-bold text-2xl",children:"Track outcomes + auto-rollback"}),t("pre",{className:"rounded-lg border bg-muted p-4 text-sm",children:`import {
+});`})]}),v("div",{className:"space-y-3",children:[k(A,{className:"font-bold text-2xl",children:"Track outcomes + auto-rollback"}),k(z,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import {
   SpecExperimentAnalyzer,
   SpecExperimentController,
 } from '@contractspec/lib.growth/spec-experiments';
@@ -34,4 +34,4 @@ const controller = new SpecExperimentController({
   registry,
   analyzer,
   onRollback: (target, evaluation) => notifyOps(target, evaluation.reasons),
-});`})]}),t("div",{className:"grid gap-4 md:grid-cols-2",children:[{title:"Deterministic bucketing",description:"ExperimentRunner reuses the same hashing logic as growth experiments\u2014every user sticks to a variant."},{title:"Multi-stage rollouts",description:"Use `rolloutStages` to shift 1% \u2192 10% \u2192 50% \u2192 100%. Guardrails trigger rollbacks automatically."}].map((e)=>a("div",{className:"card-subtle space-y-2 p-4",children:[t("h3",{className:"font-semibold text-lg",children:e.title}),t("p",{className:"text-muted-foreground text-sm",children:e.description})]},e.title))})]})}export{d as AdvancedSpecExperimentsPage};
+});`})]}),k("div",{className:"grid gap-4 md:grid-cols-2",children:[{title:"Deterministic bucketing",description:"ExperimentRunner reuses the same hashing logic as growth experiments\u2014every user sticks to a variant."},{title:"Multi-stage rollouts",description:"Use `rolloutStages` to shift 1% \u2192 10% \u2192 50% \u2192 100%. Guardrails trigger rollbacks automatically."}].map((f)=>v("div",{className:"card-subtle space-y-2 p-4",children:[k(I,{className:"font-semibold text-lg",children:f.title}),k(B,{className:"text-muted-foreground text-sm",children:f.description})]},f.title))})]})}export{N as AdvancedSpecExperimentsPage};

package/dist/components/docs/advanced/index.js

@@ -1,5 +1,5 @@
 // @bun
-var h=Object.defineProperty;var y=(l)=>l;function b(l,p){this[l]=y.bind(null,p)}var P=(l,p)=>{for(var v in p)h(l,v,{get:p[v],enumerable:!0,configurable:!0,set:b.bind(p,v)})};var A=(l,p)=>()=>(l&&(p=l(l=0)),p);import g from"@contractspec/lib.ui-link";import{ChevronRight as N}from"lucide-react";import{jsx as t,jsxs as r}from"react/jsx-runtime";function I(){return r("div",{className:"space-y-8",children:[r("div",{className:"space-y-4",children:[t("h1",{className:"font-bold text-4xl",children:"MCP Adapters"}),r("p",{className:"text-muted-foreground",children:["The ",t("strong",{children:"Model Context Protocol (MCP)"})," is an open standard for connecting AI models to external tools and data sources. ContractSpec provides MCP adapters that allow you to expose your capabilities as MCP tools and consume external MCP servers as capabilities."]})]}),r("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Why MCP integration matters"}),t("p",{className:"text-muted-foreground",children:"AI agents need access to real-world tools and data to be useful. MCP provides a standardized way to expose these capabilities. By integrating ContractSpec with MCP, you can:"}),r("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"Let AI agents invoke your ContractSpec capabilities safely and securely"}),t("li",{children:"Use external MCP servers (databases, APIs, search engines) as capability providers in your workflows"}),t("li",{children:"Build AI-powered features without writing custom integration code"}),t("li",{children:"Enforce policies on AI agent actions just like any other user"})]})]}),r("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Exposing capabilities as MCP tools"}),r("p",{className:"text-muted-foreground",children:["Any"," ",t(g,{href:"/docs/specs/capabilities",className:"text-violet-400 hover:text-violet-300",children:"CapabilitySpec"})," ","can be automatically exposed as an MCP tool. ContractSpec generates:"]}),r("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"A tool schema describing the capability's inputs, outputs, and purpose"}),t("li",{children:"An MCP server endpoint that AI agents can connect to"}),t("li",{children:"Policy enforcement ensuring agents can only invoke capabilities they're authorized to use"}),t("li",{children:"Audit logging of all agent actions for compliance and debugging"})]})]}),r("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Example: Exposing a capability"}),t("p",{className:"text-muted-foreground",children:"Here's how to expose ContractSpec operations as MCP tools:"}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+var N=Object.defineProperty;var w=(l)=>l;function k(l,p){this[l]=w.bind(null,p)}var R=(l,p)=>{for(var f in p)N(l,f,{get:p[f],enumerable:!0,configurable:!0,set:k.bind(p,f)})};var L=(l,p)=>()=>(l&&(p=l(l=0)),p);import g from"@contractspec/lib.ui-link";import{ChevronRight as S}from"lucide-react";import{jsx as t,jsxs as a}from"react/jsx-runtime";function U(){return a("div",{className:"space-y-8",children:[a("div",{className:"space-y-4",children:[t("h1",{className:"font-bold text-4xl",children:"MCP Adapters"}),a("p",{className:"text-muted-foreground",children:["The ",t("strong",{children:"Model Context Protocol (MCP)"})," is an open standard for connecting AI models to external tools and data sources. ContractSpec provides MCP adapters that allow you to expose your capabilities as MCP tools and consume external MCP servers as capabilities."]})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Why MCP integration matters"}),t("p",{className:"text-muted-foreground",children:"AI agents need access to real-world tools and data to be useful. MCP provides a standardized way to expose these capabilities. By integrating ContractSpec with MCP, you can:"}),a("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"Let AI agents invoke your ContractSpec capabilities safely and securely"}),t("li",{children:"Use external MCP servers (databases, APIs, search engines) as capability providers in your workflows"}),t("li",{children:"Build AI-powered features without writing custom integration code"}),t("li",{children:"Enforce policies on AI agent actions just like any other user"})]})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Exposing capabilities as MCP tools"}),a("p",{className:"text-muted-foreground",children:["Any"," ",t(g,{href:"/docs/specs/capabilities",className:"text-violet-400 hover:text-violet-300",children:"CapabilitySpec"})," ","can be automatically exposed as an MCP tool. ContractSpec generates:"]}),a("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"A tool schema describing the capability's inputs, outputs, and purpose"}),t("li",{children:"An MCP server endpoint that AI agents can connect to"}),t("li",{children:"Policy enforcement ensuring agents can only invoke capabilities they're authorized to use"}),t("li",{children:"Audit logging of all agent actions for compliance and debugging"})]})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Example: Exposing a capability"}),t("p",{className:"text-muted-foreground",children:"Here's how to expose ContractSpec operations as MCP tools:"}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMcpServer } from '@contractspec/lib.contracts-runtime-server-mcp/provider-mcp';
 import { registry, resources, prompts } from './lib/registry';
@@ -16,7 +16,7 @@ createMcpServer(server, registry, resources, prompts, {
 });
 
 const transport = new StdioServerTransport();
-await server.connect(transport);`})}),t("p",{className:"text-muted-foreground",children:"AI agents can now discover and invoke your operations through the MCP protocol. ContractSpec handles authentication, authorization, and execution automatically via the `OperationSpecRegistry`."})]}),r("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Consuming external MCP servers"}),t("p",{className:"text-muted-foreground",children:"You can integrate external MCP servers into your workflows. Define an integration spec and use it in your operations:"}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`import { defineIntegration } from '@contractspec/lib.contracts-integrations';
+await server.connect(transport);`})}),t("p",{className:"text-muted-foreground",children:"AI agents can now discover and invoke your operations through the MCP protocol. ContractSpec handles authentication, authorization, and execution automatically via the `OperationSpecRegistry`."})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Consuming external MCP servers"}),t("p",{className:"text-muted-foreground",children:"You can integrate external MCP servers into your workflows. Define an integration spec and use it in your operations:"}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`import { defineIntegration } from '@contractspec/lib.contracts-integrations';
 import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
 
 const SearchProductsIntegration = defineIntegration({
@@ -45,7 +45,7 @@ const SearchProductsIntegration = defineIntegration({
       },
     }),
   },
-});`})})]}),r("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Policy enforcement for AI agents"}),r("p",{className:"text-muted-foreground",children:["AI agents are treated like any other actor in ContractSpec. They must authenticate, and all their actions are subject to"," ",t(g,{href:"/docs/specs/policy",className:"text-violet-400 hover:text-violet-300",children:"PolicySpecs"}),". You can define specific policies in TypeScript:"]}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`import { definePolicy } from '@contractspec/lib.contracts-spec';
+});`})})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Policy enforcement for AI agents"}),a("p",{className:"text-muted-foreground",children:["AI agents are treated like any other actor in ContractSpec. They must authenticate, and all their actions are subject to"," ",t(g,{href:"/docs/specs/policy",className:"text-violet-400 hover:text-violet-300",children:"PolicySpecs"}),". You can define specific policies in TypeScript:"]}),t("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:t("pre",{children:`import { definePolicy } from '@contractspec/lib.contracts-spec';
 
 export const AIAgentRestrictions = definePolicy({
   meta: {
@@ -68,7 +68,7 @@ export const AIAgentRestrictions = definePolicy({
         !ctx.approvalGranted,
     },
   ],
-});`})})]}),r("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Human-in-the-loop workflows"}),t("p",{className:"text-muted-foreground",children:"For sensitive operations, you can require human approval before an AI agent can proceed. ContractSpec provides built-in approval workflows:"}),r("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"Agent requests permission to invoke a capability"}),t("li",{children:"Request is sent to designated approvers (via email, Slack, etc.)"}),t("li",{children:"Approver reviews the request and approves or denies it"}),t("li",{children:"Agent receives the decision and can proceed if approved"})]}),r("p",{className:"text-muted-foreground",children:["All approval decisions are logged in the"," ",t(g,{href:"/docs/safety/auditing",className:"text-violet-400 hover:text-violet-300",children:"audit log"}),"."]})]}),r("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Best practices"}),r("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"Start with read-only capabilities for AI agents\u2014only grant write access when necessary."}),t("li",{children:"Use human-in-the-loop approval for any capability that modifies critical data or triggers financial transactions."}),t("li",{children:"Set rate limits to prevent runaway agents from overwhelming your system."}),t("li",{children:"Provide clear, detailed descriptions for each capability so agents know when to use them."}),t("li",{children:"Monitor agent actions closely in production and adjust policies as needed."}),t("li",{children:"Test agent integrations thoroughly with realistic scenarios before deploying."})]})]}),r("div",{className:"flex items-center gap-4 pt-4",children:[t(g,{href:"/docs/advanced/renderers",className:"btn-ghost",children:"Previous: Custom Renderers"}),r(g,{href:"/docs/advanced/telemetry",className:"btn-primary",children:["Next: Telemetry ",t(N,{size:16})]})]})]})}import w from"@contractspec/lib.ui-link";import{jsx as a,jsxs as d}from"react/jsx-runtime";function q(){return d("div",{className:"space-y-8",children:[d("div",{className:"space-y-4",children:[a("h1",{className:"font-bold text-4xl",children:"Overlay Editor"}),a("p",{className:"text-lg text-muted-foreground",children:"A Next.js app (`@contractspec/app.overlay-editor`) that lets tenant admins tweak field visibility, labels, and ordering, then sign OverlaySpecs."})]}),d("div",{className:"space-y-4",children:[a("h2",{className:"font-bold text-2xl",children:"Features"}),d("ul",{className:"list-disc space-y-2 pl-6",children:[a("li",{children:"Toggle visibility and rename labels without touching code."}),a("li",{children:"Move fields up/down to define the overlay order."}),a("li",{children:"Preview JSON output powered by `@contractspec/lib.overlay-engine`."}),a("li",{children:"Server action for PEM signing (Ed25519/RSA-PSS)."})]}),d("p",{children:["Project path: ",a("code",{children:"packages/apps/overlay-editor"})]})]}),d("div",{className:"space-y-4",children:[a("h2",{className:"font-bold text-2xl",children:"Provisioning flow"}),d("ol",{className:"list-decimal space-y-2 pl-6",children:[d("li",{children:["Clone the repo and run ",a("code",{children:"bun dev"})," inside the app."]}),a("li",{children:"Use the UI to craft the overlay for a tenant."}),a("li",{children:"Paste the tenant's PEM private key (stored in Vault/KMS)."}),a("li",{children:"Click \u201CSign overlay\u201D to get the final JSON payload."}),a("li",{children:"Persist in the `Overlay` table and register with `OverlayRegistry`."})]}),d("p",{children:["See also:"," ",a(w,{href:"/docs/ops/tenant-customization",className:"text-violet-400 underline",children:"Tenant customization runbook"}),"."]})]})]})}import k from"@contractspec/lib.ui-link";import{ChevronRight as S}from"lucide-react";import{jsx as i,jsxs as c}from"react/jsx-runtime";function _(){return c("div",{className:"space-y-8",children:[c("div",{className:"space-y-2",children:[i("h1",{className:"font-bold text-4xl",children:"Custom Renderers"}),i("p",{className:"text-lg text-muted-foreground",children:"ContractSpec ships with React and React Native renderers. You can build custom renderers for any framework."})]}),c("div",{className:"space-y-6",children:[c("div",{className:"space-y-3",children:[i("h2",{className:"font-bold text-2xl",children:"Overview"}),c("p",{className:"text-muted-foreground",children:["The presentation runtime libraries (",i("code",{children:"@contractspec/lib.presentation-runtime-react"})," and",i("code",{children:"@contractspec/lib.presentation-runtime-react-native"}),") provide hooks and components to render ContractSpec-defined UI like workflows and data views. You can extend these or create custom implementations for other frameworks."]})]}),c("div",{className:"space-y-3",children:[i("h2",{className:"font-bold text-2xl",children:"Using the React Renderer"}),i("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:i("pre",{children:`import { useWorkflow, WorkflowStepRenderer } from '@contractspec/lib.presentation-runtime-react';
+});`})})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Human-in-the-loop workflows"}),t("p",{className:"text-muted-foreground",children:"For sensitive operations, you can require human approval before an AI agent can proceed. ContractSpec provides built-in approval workflows:"}),a("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"Agent requests permission to invoke a capability"}),t("li",{children:"Request is sent to designated approvers (via email, Slack, etc.)"}),t("li",{children:"Approver reviews the request and approves or denies it"}),t("li",{children:"Agent receives the decision and can proceed if approved"})]}),a("p",{className:"text-muted-foreground",children:["All approval decisions are logged in the"," ",t(g,{href:"/docs/safety/auditing",className:"text-violet-400 hover:text-violet-300",children:"audit log"}),"."]})]}),a("div",{className:"space-y-4",children:[t("h2",{className:"font-bold text-2xl",children:"Best practices"}),a("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[t("li",{children:"Start with read-only capabilities for AI agents\u2014only grant write access when necessary."}),t("li",{children:"Use human-in-the-loop approval for any capability that modifies critical data or triggers financial transactions."}),t("li",{children:"Set rate limits to prevent runaway agents from overwhelming your system."}),t("li",{children:"Provide clear, detailed descriptions for each capability so agents know when to use them."}),t("li",{children:"Monitor agent actions closely in production and adjust policies as needed."}),t("li",{children:"Test agent integrations thoroughly with realistic scenarios before deploying."})]})]}),a("div",{className:"flex items-center gap-4 pt-4",children:[t(g,{href:"/docs/advanced/renderers",className:"btn-ghost",children:"Previous: Custom Renderers"}),a(g,{href:"/docs/advanced/telemetry",className:"btn-primary",children:["Next: Telemetry ",t(S,{size:16})]})]})]})}import C from"@contractspec/lib.ui-link";import{jsx as r,jsxs as d}from"react/jsx-runtime";function Y(){return d("div",{className:"space-y-8",children:[d("div",{className:"space-y-4",children:[r("h1",{className:"font-bold text-4xl",children:"Overlay Editor"}),r("p",{className:"text-lg text-muted-foreground",children:"A Next.js app (`@contractspec/app.overlay-editor`) that lets tenant admins tweak field visibility, labels, and ordering, then sign OverlaySpecs."})]}),d("div",{className:"space-y-4",children:[r("h2",{className:"font-bold text-2xl",children:"Features"}),d("ul",{className:"list-disc space-y-2 pl-6",children:[r("li",{children:"Toggle visibility and rename labels without touching code."}),r("li",{children:"Move fields up/down to define the overlay order."}),r("li",{children:"Preview JSON output powered by `@contractspec/lib.overlay-engine`."}),r("li",{children:"Server action for PEM signing (Ed25519/RSA-PSS)."})]}),d("p",{children:["Project path: ",r("code",{children:"packages/apps/overlay-editor"})]})]}),d("div",{className:"space-y-4",children:[r("h2",{className:"font-bold text-2xl",children:"Provisioning flow"}),d("ol",{className:"list-decimal space-y-2 pl-6",children:[d("li",{children:["Clone the repo and run ",r("code",{children:"bun dev"})," inside the app."]}),r("li",{children:"Use the UI to craft the overlay for a tenant."}),r("li",{children:"Paste the tenant's PEM private key (stored in Vault/KMS)."}),r("li",{children:"Click \u201CSign overlay\u201D to get the final JSON payload."}),r("li",{children:"Persist in the `Overlay` table and register with `OverlayRegistry`."})]}),d("p",{children:["See also:"," ",r(C,{href:"/docs/ops/tenant-customization",className:"text-violet-400 underline",children:"Tenant customization runbook"}),"."]})]})]})}import P from"@contractspec/lib.ui-link";import{ChevronRight as A}from"lucide-react";import{jsx as i,jsxs as s}from"react/jsx-runtime";function V(){return s("div",{className:"space-y-8",children:[s("div",{className:"space-y-2",children:[i("h1",{className:"font-bold text-4xl",children:"Custom Renderers"}),i("p",{className:"text-lg text-muted-foreground",children:"ContractSpec ships with React and React Native renderers. You can build custom renderers for any framework."})]}),s("div",{className:"space-y-6",children:[s("div",{className:"space-y-3",children:[i("h2",{className:"font-bold text-2xl",children:"Overview"}),s("p",{className:"text-muted-foreground",children:["The presentation runtime libraries (",i("code",{children:"@contractspec/lib.presentation-runtime-react"})," and",i("code",{children:"@contractspec/lib.presentation-runtime-react-native"}),") provide hooks and components to render ContractSpec-defined UI like workflows and data views. You can extend these or create custom implementations for other frameworks."]})]}),s("div",{className:"space-y-3",children:[i("h2",{className:"font-bold text-2xl",children:"Using the React Renderer"}),i("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:i("pre",{children:`import { useWorkflow, WorkflowStepRenderer } from '@contractspec/lib.presentation-runtime-react';
 import { MyWorkflowSpec } from './specs';
 
 export function WorkflowPage() {
@@ -83,7 +83,7 @@ export function WorkflowPage() {
       </button>
     </div>
   );
-}`})})]}),c("div",{className:"space-y-3",children:[i("h2",{className:"font-bold text-2xl",children:"Custom Platform Support"}),i("p",{className:"text-muted-foreground",children:"To support a new platform (e.g., Vue, Svelte), you would:"}),c("ol",{className:"list-inside list-decimal space-y-2 text-muted-foreground",children:[c("li",{children:["Implement the core workflow state machine (from"," ",i("code",{children:"@contractspec/lib.presentation-runtime-core"}),")"]}),i("li",{children:"Create framework-specific hooks/components for step rendering"}),i("li",{children:"Handle validation and submission via the ContractSpec I/O schemas"})]})]}),i("div",{className:"flex items-center gap-4 pt-4",children:c(k,{href:"/docs",className:"btn-primary",children:["Back to docs ",i(S,{size:16})]})})]})]})}import{jsx as s,jsxs as u}from"react/jsx-runtime";function B(){return u("div",{className:"space-y-8",children:[u("div",{className:"space-y-4",children:[s("h1",{className:"font-bold text-4xl",children:"Spec Experiments"}),s("p",{className:"text-lg text-muted-foreground",children:"Run controlled experiments on ContractSpec operations, gradually shift traffic, and roll back automatically when guardrails trip."})]}),u("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"Define control + variants"}),s("pre",{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { SpecExperimentRegistry } from '@contractspec/lib.growth/spec-experiments';
+}`})})]}),s("div",{className:"space-y-3",children:[i("h2",{className:"font-bold text-2xl",children:"Custom Platform Support"}),i("p",{className:"text-muted-foreground",children:"To support a new platform (e.g., Vue, Svelte), you would:"}),s("ol",{className:"list-inside list-decimal space-y-2 text-muted-foreground",children:[s("li",{children:["Implement the core workflow state machine (from"," ",i("code",{children:"@contractspec/lib.presentation-runtime-core"}),")"]}),i("li",{children:"Create framework-specific hooks/components for step rendering"}),i("li",{children:"Handle validation and submission via the ContractSpec I/O schemas"})]})]}),i("div",{className:"flex items-center gap-4 pt-4",children:s(P,{href:"/docs",className:"btn-primary",children:["Back to docs ",i(A,{size:16})]})})]})]})}import{Code as v,H1 as M,H2 as h,H3 as T,P as y}from"@contractspec/lib.design-system/components/typography";import{jsx as c,jsxs as u}from"react/jsx-runtime";function H(){return u("div",{className:"space-y-8",children:[u("div",{className:"space-y-4",children:[c(M,{className:"font-bold text-4xl",children:"Spec Experiments"}),c(y,{className:"text-lg text-muted-foreground",children:"Run controlled experiments on ContractSpec operations, gradually shift traffic, and roll back automatically when guardrails trip."})]}),u("div",{className:"space-y-3",children:[c(h,{className:"font-bold text-2xl",children:"Define control + variants"}),c(v,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { SpecExperimentRegistry } from '@contractspec/lib.growth/spec-experiments';
 
 const registry = new SpecExperimentRegistry().register({
   target: { name: 'billing.createInvoice', version: 4 },
@@ -103,12 +103,12 @@ const registry = new SpecExperimentRegistry().register({
   ],
   rolloutStages: [0.01, 0.1, 0.5, 1],
   guardrails: { errorRateThreshold: 0.02, latencyP99ThresholdMs: 500 },
-});`})]}),u("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"Attach to runtime"}),s("pre",{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { createSpecVariantResolver } from '@contractspec/lib.growth/spec-experiments';
+});`})]}),u("div",{className:"space-y-3",children:[c(h,{className:"font-bold text-2xl",children:"Attach to runtime"}),c(v,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { createSpecVariantResolver } from '@contractspec/lib.growth/spec-experiments';
 
 adapterContext.specVariantResolver = createSpecVariantResolver({
   adapter,
   resolveUserId: (ctx) => ctx.userId ?? ctx.organizationId ?? 'anon',
-});`})]}),u("div",{className:"space-y-3",children:[s("h2",{className:"font-bold text-2xl",children:"Track outcomes + auto-rollback"}),s("pre",{className:"rounded-lg border bg-muted p-4 text-sm",children:`import {
+});`})]}),u("div",{className:"space-y-3",children:[c(h,{className:"font-bold text-2xl",children:"Track outcomes + auto-rollback"}),c(v,{className:"rounded-lg border bg-muted p-4 text-sm",children:`import {
   SpecExperimentAnalyzer,
   SpecExperimentController,
 } from '@contractspec/lib.growth/spec-experiments';
@@ -118,7 +118,7 @@ const controller = new SpecExperimentController({
   registry,
   analyzer,
   onRollback: (target, evaluation) => notifyOps(target, evaluation.reasons),
-});`})]}),s("div",{className:"grid gap-4 md:grid-cols-2",children:[{title:"Deterministic bucketing",description:"ExperimentRunner reuses the same hashing logic as growth experiments\u2014every user sticks to a variant."},{title:"Multi-stage rollouts",description:"Use `rolloutStages` to shift 1% \u2192 10% \u2192 50% \u2192 100%. Guardrails trigger rollbacks automatically."}].map((l)=>u("div",{className:"card-subtle space-y-2 p-4",children:[s("h3",{className:"font-semibold text-lg",children:l.title}),s("p",{className:"text-muted-foreground text-sm",children:l.description})]},l.title))})]})}import f from"@contractspec/lib.ui-link";import{ChevronRight as C}from"lucide-react";import{jsx as e,jsxs as o}from"react/jsx-runtime";function K(){return o("div",{className:"space-y-8",children:[o("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"Telemetry"}),o("p",{className:"text-muted-foreground",children:["A ",e("strong",{children:"TelemetrySpec"})," defines what metrics, logs, and traces to collect for observability. ContractSpec automatically instruments your application based on these specs, ensuring you have the visibility you need to monitor, debug, and optimize your system."]})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Why telemetry matters"}),e("p",{className:"text-muted-foreground",children:"You can't fix what you can't see. Telemetry provides visibility into how your application is performing, where errors are occurring, and how users are interacting with your system. Without proper instrumentation, you're flying blind in production."}),e("p",{className:"text-muted-foreground",children:"ContractSpec takes a spec-first approach to telemetry: you declare what you want to observe, and runtime adapters instrument operations automatically. This ensures consistent, comprehensive coverage without manual effort."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Three pillars of observability"}),o("div",{className:"space-y-3",children:[o("div",{children:[e("h3",{className:"font-semibold text-lg",children:"Metrics"}),e("p",{className:"text-muted-foreground",children:"Numerical measurements collected over time. Examples: request count, error rate, latency percentiles, active users, queue depth. Metrics are cheap to collect and store, making them ideal for high-level monitoring and alerting."})]}),o("div",{children:[e("h3",{className:"font-semibold text-lg",children:"Logs"}),e("p",{className:"text-muted-foreground",children:'Timestamped text records of events. Examples: "User 123 logged in", "Payment failed for order 456", "Database connection pool exhausted". Logs provide detailed context for debugging specific issues.'})]}),o("div",{children:[e("h3",{className:"font-semibold text-lg",children:"Traces"}),e("p",{className:"text-muted-foreground",children:"Records of requests as they flow through your system. A trace shows the complete path of a request\u2014which services it touched, how long each step took, and where errors occurred. Traces are essential for debugging distributed systems."})]})]})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Example TelemetrySpec"}),e("p",{className:"text-muted-foreground",children:"Here's how telemetry is configured in TypeScript:"}),e("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:e("pre",{children:`import { defineTelemetry } from '@contractspec/lib.contracts-spec/telemetry';
+});`})]}),c("div",{className:"grid gap-4 md:grid-cols-2",children:[{title:"Deterministic bucketing",description:"ExperimentRunner reuses the same hashing logic as growth experiments\u2014every user sticks to a variant."},{title:"Multi-stage rollouts",description:"Use `rolloutStages` to shift 1% \u2192 10% \u2192 50% \u2192 100%. Guardrails trigger rollbacks automatically."}].map((l)=>u("div",{className:"card-subtle space-y-2 p-4",children:[c(T,{className:"font-semibold text-lg",children:l.title}),c(y,{className:"text-muted-foreground text-sm",children:l.description})]},l.title))})]})}import b from"@contractspec/lib.ui-link";import{ChevronRight as I}from"lucide-react";import{jsx as e,jsxs as o}from"react/jsx-runtime";function j(){return o("div",{className:"space-y-8",children:[o("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"Telemetry"}),o("p",{className:"text-muted-foreground",children:["A ",e("strong",{children:"TelemetrySpec"})," defines what metrics, logs, and traces to collect for observability. ContractSpec automatically instruments your application based on these specs, ensuring you have the visibility you need to monitor, debug, and optimize your system."]})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Why telemetry matters"}),e("p",{className:"text-muted-foreground",children:"You can't fix what you can't see. Telemetry provides visibility into how your application is performing, where errors are occurring, and how users are interacting with your system. Without proper instrumentation, you're flying blind in production."}),e("p",{className:"text-muted-foreground",children:"ContractSpec takes a spec-first approach to telemetry: you declare what you want to observe, and runtime adapters instrument operations automatically. This ensures consistent, comprehensive coverage without manual effort."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Three pillars of observability"}),o("div",{className:"space-y-3",children:[o("div",{children:[e("h3",{className:"font-semibold text-lg",children:"Metrics"}),e("p",{className:"text-muted-foreground",children:"Numerical measurements collected over time. Examples: request count, error rate, latency percentiles, active users, queue depth. Metrics are cheap to collect and store, making them ideal for high-level monitoring and alerting."})]}),o("div",{children:[e("h3",{className:"font-semibold text-lg",children:"Logs"}),e("p",{className:"text-muted-foreground",children:'Timestamped text records of events. Examples: "User 123 logged in", "Payment failed for order 456", "Database connection pool exhausted". Logs provide detailed context for debugging specific issues.'})]}),o("div",{children:[e("h3",{className:"font-semibold text-lg",children:"Traces"}),e("p",{className:"text-muted-foreground",children:"Records of requests as they flow through your system. A trace shows the complete path of a request\u2014which services it touched, how long each step took, and where errors occurred. Traces are essential for debugging distributed systems."})]})]})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Example TelemetrySpec"}),e("p",{className:"text-muted-foreground",children:"Here's how telemetry is configured in TypeScript:"}),e("div",{className:"overflow-x-auto rounded-lg border border-border bg-background/50 p-4 font-mono text-muted-foreground text-sm",children:e("pre",{children:`import { defineTelemetry } from '@contractspec/lib.contracts-spec/telemetry';
 
 export const OrderProcessingTelemetry = defineTelemetry({
   meta: {
@@ -163,7 +163,7 @@ export const OrderProcessingTelemetry = defineTelemetry({
       notify: ['pagerduty', 'slack'],
     },
   ],
-});`})})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Automatic instrumentation"}),e("p",{className:"text-muted-foreground",children:"ContractSpec automatically instruments:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"All operations"})," \u2013 Request count, latency, error rate per Command/Query"]}),o("li",{children:[e("strong",{children:"All workflows"})," \u2013 Step execution time, retry counts, compensation events"]}),o("li",{children:[e("strong",{children:"All data views"})," \u2013 Query execution time, result set size"]}),o("li",{children:[e("strong",{children:"All policy decisions"})," \u2013 Decision time, permit/deny ratio"]}),o("li",{children:[e("strong",{children:"System resources"})," \u2013 CPU, memory, disk, network usage"]})]}),e("p",{className:"text-muted-foreground",children:"You don't need to add instrumentation code manually\u2014the runtime handles it based on your specs."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Integration with observability platforms"}),e("p",{className:"text-muted-foreground",children:"ContractSpec supports multiple observability backends:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"Prometheus"})," \u2013 For metrics collection and alerting"]}),o("li",{children:[e("strong",{children:"Grafana"})," \u2013 For dashboards and visualization"]}),o("li",{children:[e("strong",{children:"Jaeger / Tempo"})," \u2013 For distributed tracing"]}),o("li",{children:[e("strong",{children:"Loki"})," \u2013 For log aggregation"]}),o("li",{children:[e("strong",{children:"Datadog"})," \u2013 All-in-one observability platform"]}),o("li",{children:[e("strong",{children:"New Relic"})," \u2013 Application performance monitoring"]}),o("li",{children:[e("strong",{children:"Honeycomb"})," \u2013 Observability for complex systems"]})]}),e("p",{className:"text-muted-foreground",children:"You can configure multiple backends and send telemetry to all of them simultaneously."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Sampling and performance"}),e("p",{className:"text-muted-foreground",children:"Collecting telemetry has a cost\u2014CPU, memory, network bandwidth, and storage. ContractSpec provides several mechanisms to control overhead:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"Sampling"})," \u2013 Trace only a percentage of requests (e.g., 10%)"]}),o("li",{children:[e("strong",{children:"Adaptive sampling"})," \u2013 Automatically reduce sampling rate under high load"]}),o("li",{children:[e("strong",{children:"Tail-based sampling"})," \u2013 Keep traces for failed requests, sample successful ones"]}),o("li",{children:[e("strong",{children:"Field redaction"})," \u2013 Remove sensitive data from traces and logs"]}),o("li",{children:[e("strong",{children:"Aggregation"})," \u2013 Pre-aggregate metrics before sending to reduce network traffic"]})]})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Best practices"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[e("li",{children:"Start with high-level metrics (request rate, error rate, latency) and add more detailed instrumentation as needed."}),e("li",{children:"Use structured logging\u2014log events with structured fields, not free-form text."}),e("li",{children:"Set up alerts for critical metrics so you're notified when things go wrong."}),e("li",{children:"Use traces to debug complex issues\u2014they show the complete picture of a request."}),e("li",{children:"Redact sensitive data from logs and traces to comply with privacy regulations."}),e("li",{children:"Review dashboards regularly to understand normal behavior\u2014this makes anomalies easier to spot."}),e("li",{children:"Use sampling to control costs, but always trace errors and slow requests."})]})]}),o("div",{className:"flex items-center gap-4 pt-4",children:[e(f,{href:"/docs/advanced/mcp",className:"btn-ghost",children:"Previous: MCP Adapters"}),o(f,{href:"/docs/comparison",className:"btn-primary",children:["Next: Comparison ",e(C,{size:16})]})]})]})}import{jsx as n,jsxs as m}from"react/jsx-runtime";function Z(){return m("div",{className:"space-y-8",children:[m("div",{className:"space-y-4",children:[n("h1",{className:"font-bold text-4xl",children:"Workflow Monitoring"}),n("p",{className:"text-lg text-muted-foreground",children:"Production workflows need robust observability. ContractSpec provides SLA monitoring, distributed tracing, and audit logging out of the box."})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"SLA Monitoring"}),m("p",{children:["Use the ",n("code",{children:"SLAMonitor"})," to detect when workflows or individual steps exceed their budgeted duration."]}),n("pre",{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { SLAMonitor } from '@contractspec/lib.contracts-spec/workflow/sla-monitor';
+});`})})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Automatic instrumentation"}),e("p",{className:"text-muted-foreground",children:"ContractSpec automatically instruments:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"All operations"})," \u2013 Request count, latency, error rate per Command/Query"]}),o("li",{children:[e("strong",{children:"All workflows"})," \u2013 Step execution time, retry counts, compensation events"]}),o("li",{children:[e("strong",{children:"All data views"})," \u2013 Query execution time, result set size"]}),o("li",{children:[e("strong",{children:"All policy decisions"})," \u2013 Decision time, permit/deny ratio"]}),o("li",{children:[e("strong",{children:"System resources"})," \u2013 CPU, memory, disk, network usage"]})]}),e("p",{className:"text-muted-foreground",children:"You don't need to add instrumentation code manually\u2014the runtime handles it based on your specs."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Integration with observability platforms"}),e("p",{className:"text-muted-foreground",children:"ContractSpec supports multiple observability backends:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"Prometheus"})," \u2013 For metrics collection and alerting"]}),o("li",{children:[e("strong",{children:"Grafana"})," \u2013 For dashboards and visualization"]}),o("li",{children:[e("strong",{children:"Jaeger / Tempo"})," \u2013 For distributed tracing"]}),o("li",{children:[e("strong",{children:"Loki"})," \u2013 For log aggregation"]}),o("li",{children:[e("strong",{children:"Datadog"})," \u2013 All-in-one observability platform"]}),o("li",{children:[e("strong",{children:"New Relic"})," \u2013 Application performance monitoring"]}),o("li",{children:[e("strong",{children:"Honeycomb"})," \u2013 Observability for complex systems"]})]}),e("p",{className:"text-muted-foreground",children:"You can configure multiple backends and send telemetry to all of them simultaneously."})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Sampling and performance"}),e("p",{className:"text-muted-foreground",children:"Collecting telemetry has a cost\u2014CPU, memory, network bandwidth, and storage. ContractSpec provides several mechanisms to control overhead:"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[o("li",{children:[e("strong",{children:"Sampling"})," \u2013 Trace only a percentage of requests (e.g., 10%)"]}),o("li",{children:[e("strong",{children:"Adaptive sampling"})," \u2013 Automatically reduce sampling rate under high load"]}),o("li",{children:[e("strong",{children:"Tail-based sampling"})," \u2013 Keep traces for failed requests, sample successful ones"]}),o("li",{children:[e("strong",{children:"Field redaction"})," \u2013 Remove sensitive data from traces and logs"]}),o("li",{children:[e("strong",{children:"Aggregation"})," \u2013 Pre-aggregate metrics before sending to reduce network traffic"]})]})]}),o("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Best practices"}),o("ul",{className:"list-inside list-disc space-y-2 text-muted-foreground",children:[e("li",{children:"Start with high-level metrics (request rate, error rate, latency) and add more detailed instrumentation as needed."}),e("li",{children:"Use structured logging\u2014log events with structured fields, not free-form text."}),e("li",{children:"Set up alerts for critical metrics so you're notified when things go wrong."}),e("li",{children:"Use traces to debug complex issues\u2014they show the complete picture of a request."}),e("li",{children:"Redact sensitive data from logs and traces to comply with privacy regulations."}),e("li",{children:"Review dashboards regularly to understand normal behavior\u2014this makes anomalies easier to spot."}),e("li",{children:"Use sampling to control costs, but always trace errors and slow requests."})]})]}),o("div",{className:"flex items-center gap-4 pt-4",children:[e(b,{href:"/docs/advanced/mcp",className:"btn-ghost",children:"Previous: MCP Adapters"}),o(b,{href:"/docs/comparison",className:"btn-primary",children:["Next: Comparison ",e(I,{size:16})]})]})]})}import{jsx as n,jsxs as m}from"react/jsx-runtime";function oe(){return m("div",{className:"space-y-8",children:[m("div",{className:"space-y-4",children:[n("h1",{className:"font-bold text-4xl",children:"Workflow Monitoring"}),n("p",{className:"text-lg text-muted-foreground",children:"Production workflows need robust observability. ContractSpec provides SLA monitoring, distributed tracing, and audit logging out of the box."})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"SLA Monitoring"}),m("p",{children:["Use the ",n("code",{children:"SLAMonitor"})," to detect when workflows or individual steps exceed their budgeted duration."]}),n("pre",{className:"rounded-lg border bg-muted p-4 text-sm",children:`import { SLAMonitor } from '@contractspec/lib.contracts-spec/workflow/sla-monitor';
 
 const monitor = new SLAMonitor((event, payload) => {
   if (event === 'workflow.sla_breach') {
@@ -173,4 +173,4 @@ const monitor = new SLAMonitor((event, payload) => {
 });
 
 // Check periodically
-monitor.check(currentState, workflowSpec);`})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"Telemetry & Tracing"}),n("p",{children:"Workflows automatically generate OpenTelemetry spans for:"}),m("ul",{className:"list-disc space-y-2 pl-6",children:[n("li",{children:"Overall workflow execution"}),n("li",{children:"Individual steps"}),n("li",{children:"Retries and compensation"})]}),n("p",{children:"Configure your OpenTelemetry exporter to send traces to Jaeger, Datadog, or Honeycomb."})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"Dashboarding"}),m("p",{children:["You can build a custom dashboard using ",n("code",{children:"DataViews"})," over your workflow state database. See the DataViews tutorial for how to visualize ",n("code",{children:"WorkflowState"})," records."]})]})]})}export{Z as AdvancedWorkflowMonitoringPage,K as AdvancedTelemetryPage,B as AdvancedSpecExperimentsPage,_ as AdvancedRenderersPage,q as AdvancedOverlayEditorPage,I as AdvancedMCPPage};
+monitor.check(currentState, workflowSpec);`})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"Telemetry & Tracing"}),n("p",{children:"Workflows automatically generate OpenTelemetry spans for:"}),m("ul",{className:"list-disc space-y-2 pl-6",children:[n("li",{children:"Overall workflow execution"}),n("li",{children:"Individual steps"}),n("li",{children:"Retries and compensation"})]}),n("p",{children:"Configure your OpenTelemetry exporter to send traces to Jaeger, Datadog, or Honeycomb."})]}),m("div",{className:"space-y-4",children:[n("h2",{className:"font-bold text-2xl",children:"Dashboarding"}),m("p",{children:["You can build a custom dashboard using ",n("code",{children:"DataViews"})," over your workflow state database. See the DataViews tutorial for how to visualize ",n("code",{children:"WorkflowState"})," records."]})]})]})}export{oe as AdvancedWorkflowMonitoringPage,j as AdvancedTelemetryPage,H as AdvancedSpecExperimentsPage,V as AdvancedRenderersPage,Y as AdvancedOverlayEditorPage,U as AdvancedMCPPage};