@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/components/docs/advanced/AdvancedMCPPage.tsx

@@ -0,0 +1,250 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function AdvancedMCPPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">MCP Adapters</h1>
+        <p className="text-muted-foreground">
+          The <strong>Model Context Protocol (MCP)</strong> 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.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Why MCP integration matters</h2>
+        <p className="text-muted-foreground">
+          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:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Let AI agents invoke your ContractSpec capabilities safely and
+            securely
+          </li>
+          <li>
+            Use external MCP servers (databases, APIs, search engines) as
+            capability providers in your workflows
+          </li>
+          <li>
+            Build AI-powered features without writing custom integration code
+          </li>
+          <li>Enforce policies on AI agent actions just like any other user</li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">
+          Exposing capabilities as MCP tools
+        </h2>
+        <p className="text-muted-foreground">
+          Any{' '}
+          <Link
+            href="/docs/specs/capabilities"
+            className="text-violet-400 hover:text-violet-300"
+          >
+            CapabilitySpec
+          </Link>{' '}
+          can be automatically exposed as an MCP tool. ContractSpec generates:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            A tool schema describing the capability's inputs, outputs, and
+            purpose
+          </li>
+          <li>An MCP server endpoint that AI agents can connect to</li>
+          <li>
+            Policy enforcement ensuring agents can only invoke capabilities
+            they're authorized to use
+          </li>
+          <li>
+            Audit logging of all agent actions for compliance and debugging
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Example: Exposing a capability</h2>
+        <p className="text-muted-foreground">
+          Here's how to expose ContractSpec operations as MCP tools:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMcpServer } from '@contractspec/lib.contracts/server/provider-mcp';
+import { registry, resources, prompts } from './lib/registry';
+
+const server = new McpServer({
+  name: 'my-app-mcp',
+  version: '1.0.0',
+});
+
+createMcpServer(server, registry, resources, prompts, {
+  toolCtx: () => ({ actor: 'ai-agent' }),
+  promptCtx: () => ({ userId: null, orgId: null }),
+  resourceCtx: () => ({ userId: null, orgId: null }),
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);`}</pre>
+        </div>
+        <p className="text-muted-foreground">
+          AI agents can now discover and invoke your operations through the MCP
+          protocol. ContractSpec handles authentication, authorization, and
+          execution automatically via the `OperationSpecRegistry`.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Consuming external MCP servers</h2>
+        <p className="text-muted-foreground">
+          You can integrate external MCP servers into your workflows. Define an
+          integration spec and use it in your operations:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`import { defineIntegration } from '@contractspec/lib.contracts';
+import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+
+const SearchProductsIntegration = defineIntegration({
+  meta: {
+    key: 'products.search',
+    version: '1.0.0',
+    category: 'mcp',
+    description: 'Search products via external MCP server',
+  },
+  connection: {
+    serverUrl: 'https://api.example.com/mcp',
+    toolName: 'search_products',
+  },
+  io: {
+    input: new SchemaModel({
+      name: 'SearchProductsInput',
+      fields: {
+        query: { type: ScalarTypeEnum.String(), isOptional: false },
+        category: { type: ScalarTypeEnum.String(), isOptional: true },
+      },
+    }),
+    output: new SchemaModel({
+      name: 'ProductResults',
+      fields: {
+        products: { type: ScalarTypeEnum.JSON(), isOptional: false, isArray: true },
+      },
+    }),
+  },
+});`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Policy enforcement for AI agents</h2>
+        <p className="text-muted-foreground">
+          AI agents are treated like any other actor in ContractSpec. They must
+          authenticate, and all their actions are subject to{' '}
+          <Link
+            href="/docs/specs/policy"
+            className="text-violet-400 hover:text-violet-300"
+          >
+            PolicySpecs
+          </Link>
+          . You can define specific policies in TypeScript:
+        </p>
+        <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+          <pre>{`import { definePolicy } from '@contractspec/lib.contracts';
+
+export const AIAgentRestrictions = definePolicy({
+  meta: {
+    key: 'ai.agent.restrictions',
+    version: '1.0.0',
+    description: 'Restrict AI agent actions',
+  },
+  rules: [
+    {
+      id: 'agents-read-only',
+      effect: 'DENY',
+      condition: (ctx) => ctx.actor === 'ai-agent' && ctx.action === 'write',
+    },
+    {
+      id: 'agents-require-approval',
+      effect: 'DENY',
+      condition: (ctx, spec) => 
+        ctx.actor === 'ai-agent' && 
+        spec.policy.escalate === 'human_review' &&
+        !ctx.approvalGranted,
+    },
+  ],
+});`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Human-in-the-loop workflows</h2>
+        <p className="text-muted-foreground">
+          For sensitive operations, you can require human approval before an AI
+          agent can proceed. ContractSpec provides built-in approval workflows:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>Agent requests permission to invoke a capability</li>
+          <li>
+            Request is sent to designated approvers (via email, Slack, etc.)
+          </li>
+          <li>Approver reviews the request and approves or denies it</li>
+          <li>Agent receives the decision and can proceed if approved</li>
+        </ul>
+        <p className="text-muted-foreground">
+          All approval decisions are logged in the{' '}
+          <Link
+            href="/docs/safety/auditing"
+            className="text-violet-400 hover:text-violet-300"
+          >
+            audit log
+          </Link>
+          .
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Best practices</h2>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            Start with read-only capabilities for AI agents—only grant write
+            access when necessary.
+          </li>
+          <li>
+            Use human-in-the-loop approval for any capability that modifies
+            critical data or triggers financial transactions.
+          </li>
+          <li>
+            Set rate limits to prevent runaway agents from overwhelming your
+            system.
+          </li>
+          <li>
+            Provide clear, detailed descriptions for each capability so agents
+            know when to use them.
+          </li>
+          <li>
+            Monitor agent actions closely in production and adjust policies as
+            needed.
+          </li>
+          <li>
+            Test agent integrations thoroughly with realistic scenarios before
+            deploying.
+          </li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/advanced/renderers" className="btn-ghost">
+          Previous: Custom Renderers
+        </Link>
+        <Link href="/docs/advanced/telemetry" className="btn-primary">
+          Next: Telemetry <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/advanced/AdvancedOverlayEditorPage.tsx

@@ -0,0 +1,58 @@
+import Link from '@contractspec/lib.ui-link';
+
+export function AdvancedOverlayEditorPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Overlay Editor</h1>
+        <p className="text-muted-foreground text-lg">
+          A Next.js app (`@contractspec/app.overlay-editor`) that lets tenant
+          admins tweak field visibility, labels, and ordering, then sign
+          OverlaySpecs.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Features</h2>
+        <ul className="list-disc space-y-2 pl-6">
+          <li>Toggle visibility and rename labels without touching code.</li>
+          <li>Move fields up/down to define the overlay order.</li>
+          <li>
+            Preview JSON output powered by `@contractspec/lib.overlay-engine`.
+          </li>
+          <li>Server action for PEM signing (Ed25519/RSA-PSS).</li>
+        </ul>
+        <p>
+          Project path: <code>packages/apps/overlay-editor</code>
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Provisioning flow</h2>
+        <ol className="list-decimal space-y-2 pl-6">
+          <li>
+            Clone the repo and run <code>bun dev</code> inside the app.
+          </li>
+          <li>Use the UI to craft the overlay for a tenant.</li>
+          <li>
+            Paste the tenant&apos;s PEM private key (stored in Vault/KMS).
+          </li>
+          <li>Click “Sign overlay” to get the final JSON payload.</li>
+          <li>
+            Persist in the `Overlay` table and register with `OverlayRegistry`.
+          </li>
+        </ol>
+        <p>
+          See also:{' '}
+          <Link
+            href="/docs/ops/tenant-customization"
+            className="text-violet-400 underline"
+          >
+            Tenant customization runbook
+          </Link>
+          .
+        </p>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/advanced/AdvancedRenderersPage.tsx

@@ -0,0 +1,77 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+export function AdvancedRenderersPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-2">
+        <h1 className="text-4xl font-bold">Custom Renderers</h1>
+        <p className="text-muted-foreground text-lg">
+          ContractSpec ships with React and React Native renderers. You can
+          build custom renderers for any framework.
+        </p>
+      </div>
+
+      <div className="space-y-6">
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Overview</h2>
+          <p className="text-muted-foreground">
+            The presentation runtime libraries (
+            <code>@contractspec/lib.presentation-runtime-react</code> and
+            <code>@contractspec/lib.presentation-runtime-react-native</code>)
+            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.
+          </p>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Using the React Renderer</h2>
+          <div className="bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm">
+            <pre>{`import { useWorkflow, WorkflowStepRenderer } from '@contractspec/lib.presentation-runtime-react';
+import { MyWorkflowSpec } from './specs';
+
+export function WorkflowPage() {
+  const workflow = useWorkflow(MyWorkflowSpec);
+
+  return (
+    <div>
+      <h1>{workflow.currentStep.title}</h1>
+      <WorkflowStepRenderer workflow={workflow} />
+      <button onClick={workflow.next} disabled={!workflow.canProceed}>
+        Next
+      </button>
+    </div>
+  );
+}`}</pre>
+          </div>
+        </div>
+
+        <div className="space-y-3">
+          <h2 className="text-2xl font-bold">Custom Platform Support</h2>
+          <p className="text-muted-foreground">
+            To support a new platform (e.g., Vue, Svelte), you would:
+          </p>
+          <ol className="text-muted-foreground list-inside list-decimal space-y-2">
+            <li>
+              Implement the core workflow state machine (from{' '}
+              <code>@contractspec/lib.presentation-runtime-core</code>)
+            </li>
+            <li>
+              Create framework-specific hooks/components for step rendering
+            </li>
+            <li>
+              Handle validation and submission via the ContractSpec I/O schemas
+            </li>
+          </ol>
+        </div>
+
+        <div className="flex items-center gap-4 pt-4">
+          <Link href="/docs" className="btn-primary">
+            Back to docs <ChevronRight size={16} />
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/advanced/AdvancedSpecExperimentsPage.tsx

@@ -0,0 +1,89 @@
+export function AdvancedSpecExperimentsPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Spec Experiments</h1>
+        <p className="text-muted-foreground text-lg">
+          Run controlled experiments on ContractSpec operations, gradually shift
+          traffic, and roll back automatically when guardrails trip.
+        </p>
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">Define control + variants</h2>
+        <pre className="bg-muted rounded-lg border p-4 text-sm">
+          {`import { SpecExperimentRegistry } from '@contractspec/lib.growth/spec-experiments';
+
+const registry = new SpecExperimentRegistry().register({
+  target: { name: 'billing.createInvoice', version: 4 },
+  experiment: {
+    key: 'billing.createInvoice.evolution',
+    version: '1.0.0',
+    goal: 'Reduce PO validation failures',
+    primaryMetric: 'latency_ms',
+    variants: [
+      { id: 'control' },
+      { id: 'po-required', description: 'Force PO field', weight: 1 },
+    ],
+  },
+  control: BillingCreateInvoiceV4,
+  variants: [
+    { id: 'po-required', spec: BillingCreateInvoiceForAcme },
+  ],
+  rolloutStages: [0.01, 0.1, 0.5, 1],
+  guardrails: { errorRateThreshold: 0.02, latencyP99ThresholdMs: 500 },
+});`}
+        </pre>
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">Attach to runtime</h2>
+        <pre className="bg-muted rounded-lg border p-4 text-sm">
+          {`import { createSpecVariantResolver } from '@contractspec/lib.growth/spec-experiments';
+
+adapterContext.specVariantResolver = createSpecVariantResolver({
+  adapter,
+  resolveUserId: (ctx) => ctx.userId ?? ctx.organizationId ?? 'anon',
+});`}
+        </pre>
+      </div>
+
+      <div className="space-y-3">
+        <h2 className="text-2xl font-bold">Track outcomes + auto-rollback</h2>
+        <pre className="bg-muted rounded-lg border p-4 text-sm">
+          {`import {
+  SpecExperimentAnalyzer,
+  SpecExperimentController,
+} from '@contractspec/lib.growth/spec-experiments';
+
+const analyzer = new SpecExperimentAnalyzer(tracker);
+const controller = new SpecExperimentController({
+  registry,
+  analyzer,
+  onRollback: (target, evaluation) => notifyOps(target, evaluation.reasons),
+});`}
+        </pre>
+      </div>
+
+      <div className="grid gap-4 md:grid-cols-2">
+        {[
+          {
+            title: 'Deterministic bucketing',
+            description:
+              'ExperimentRunner reuses the same hashing logic as growth experiments—every user sticks to a variant.',
+          },
+          {
+            title: 'Multi-stage rollouts',
+            description:
+              'Use `rolloutStages` to shift 1% → 10% → 50% → 100%. Guardrails trigger rollbacks automatically.',
+          },
+        ].map((card) => (
+          <div key={card.title} className="card-subtle space-y-2 p-4">
+            <h3 className="text-lg font-semibold">{card.title}</h3>
+            <p className="text-muted-foreground text-sm">{card.description}</p>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}