@contractspec/bundle.library 0.0.0-canary-20260206014742

package/src/components/docs/specs/SpecsPolicyPage.tsx

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

package/src/components/docs/specs/SpecsWorkflowsPage.tsx

@@ -0,0 +1,225 @@
+import Link from '@contractspec/lib.ui-link';
+import { ChevronRight } from 'lucide-react';
+
+// export const metadata = {
+//   title: 'Workflows: ContractSpec Docs',
+//   description:
+//     'Learn how to define multi-step workflows with retries, compensation, and monitoring in ContractSpec.',
+// };
+
+export function SpecsWorkflowsPage() {
+  return (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h1 className="text-4xl font-bold">Workflows</h1>
+        <p className="text-muted-foreground">
+          A <strong>WorkflowSpec</strong> orchestrates multi-step processes. It
+          defines the sequence of operations, handles failures with retries and
+          compensation, and provides observability into long-running tasks.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Core concepts</h2>
+        <div className="space-y-3">
+          <div>
+            <h3 className="text-lg font-semibold">Identifiers</h3>
+            <p className="text-muted-foreground">
+              Each workflow has a unique{' '}
+              <code className="bg-background/50 rounded px-2 py-1">
+                workflowId
+              </code>{' '}
+              and a{' '}
+              <code className="bg-background/50 rounded px-2 py-1">
+                version
+              </code>
+              . This allows you to run multiple versions of the same workflow
+              simultaneously during migrations or A/B tests.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Steps</h3>
+            <p className="text-muted-foreground">
+              A workflow is composed of <strong>steps</strong>. Each step
+              invokes a{' '}
+              <Link
+                href="/docs/specs/capabilities"
+                className="text-violet-400 hover:text-violet-300"
+              >
+                CapabilitySpec
+              </Link>
+              , passes inputs, and receives outputs. Steps can run sequentially
+              or in parallel.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Transitions</h3>
+            <p className="text-muted-foreground">
+              <strong>Transitions</strong> 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.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Retries</h3>
+            <p className="text-muted-foreground">
+              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.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">Compensation</h3>
+            <p className="text-muted-foreground">
+              When a workflow fails partway through,{' '}
+              <strong>compensation</strong> steps undo the effects of completed
+              steps (e.g., refunding a payment, releasing a reservation). This
+              ensures consistency even in failure scenarios.
+            </p>
+          </div>
+          <div>
+            <h3 className="text-lg font-semibold">SLAs</h3>
+            <p className="text-muted-foreground">
+              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.
+            </p>
+          </div>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">
+          Example WorkflowSpec (TypeScript)
+        </h2>
+        <p className="text-muted-foreground">
+          Here's a simplified example of a payment workflow 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 { 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,
+  },
+});`}</pre>
+        </div>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Triggers</h2>
+        <p className="text-muted-foreground">
+          Workflows can be triggered in several ways:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>
+            <strong>Manual invocation</strong> – A user or system calls the
+            workflow via an API endpoint.
+          </li>
+          <li>
+            <strong>Event-driven</strong> – The workflow starts automatically
+            when a specific event occurs (e.g., a new order is created).
+          </li>
+          <li>
+            <strong>Scheduled</strong> – The workflow runs on a cron schedule
+            (e.g., nightly batch processing).
+          </li>
+          <li>
+            <strong>Chained</strong> – One workflow can invoke another as a
+            step.
+          </li>
+        </ul>
+      </div>
+
+      <div className="space-y-4">
+        <h2 className="text-2xl font-bold">Monitoring and versioning</h2>
+        <p className="text-muted-foreground">
+          ContractSpec automatically instruments workflows with telemetry. You
+          can view:
+        </p>
+        <ul className="text-muted-foreground list-inside list-disc space-y-2">
+          <li>Real-time execution status for each step</li>
+          <li>Historical run data and success/failure rates</li>
+          <li>Latency distributions and SLA compliance</li>
+          <li>Compensation events and retry attempts</li>
+        </ul>
+        <p className="text-muted-foreground">
+          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.
+        </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>
+            Keep steps idempotent – they should be safe to retry without side
+            effects.
+          </li>
+          <li>
+            Define compensation for any step that modifies external state.
+          </li>
+          <li>Use meaningful step IDs that describe the operation.</li>
+          <li>Set realistic SLAs and monitor them in production.</li>
+          <li>Test failure scenarios locally before deploying.</li>
+        </ul>
+      </div>
+
+      <div className="flex items-center gap-4 pt-4">
+        <Link href="/docs/specs/capabilities" className="btn-ghost">
+          Previous: Capabilities
+        </Link>
+        <Link href="/docs/safety" className="btn-primary">
+          Next: Safety Features <ChevronRight size={16} />
+        </Link>
+      </div>
+    </div>
+  );
+}

package/src/components/docs/specs/index.ts

@@ -0,0 +1,6 @@
+export { SpecsOverviewPage } from './SpecsOverviewPage';
+export { SpecsCapabilitiesPage } from './SpecsCapabilitiesPage';
+export { SpecsDataViewsPage } from './SpecsDataViewsPage';
+export { SpecsWorkflowsPage } from './SpecsWorkflowsPage';
+export { SpecsPolicyPage } from './SpecsPolicyPage';
+export { SpecsOverlaysPage } from './SpecsOverlaysPage';

package/src/components/docs/studio/StudioBYOKPage.tsx

@@ -0,0 +1,60 @@
+// export const metadata: Metadata = {
+//   title: 'Studio – BYOK Setup',
+//   description:
+//     'Configure Bring Your Own Key for ContractSpec Studio. Secure credentials, rotate keys, and audit access.',
+// };
+
+const steps = [
+  {
+    title: '1. Provide vault endpoint',
+    body: 'Enter your Vault/HSM URL and the key identifier. Studio only stores the reference.',
+  },
+  {
+    title: '2. Verify encryption',
+    body: 'Studio runs a test by encrypting a dummy payload and asking you to decrypt it.',
+  },
+  {
+    title: '3. Store credentials',
+    body: 'When integrations are connected, secrets get encrypted client side before landing in the database.',
+  },
+  {
+    title: '4. Rotate keys',
+    body: 'Trigger rotation from the BYOK manager. Studio fetches existing secrets, decrypts with the old key, and re-encrypts with the new one.',
+  },
+];
+
+export function StudioBYOKPage() {
+  return (
+    <main className="space-y-12 py-12">
+      <header className="space-y-3">
+        <p className="text-xs font-semibold tracking-[0.3em] text-violet-400 uppercase">
+          BYOK
+        </p>
+        <h1 className="text-4xl font-bold">Bring your own key to Studio</h1>
+        <p className="text-muted-foreground max-w-3xl text-lg">
+          Keep secrets under your control. Studio never touches plaintext
+          credentials; everything is encrypted with tenant-specific material.
+        </p>
+      </header>
+      <section className="grid gap-4 md:grid-cols-2">
+        {steps.map((step) => (
+          <article key={step.title} className="card-subtle space-y-2 p-6">
+            <h2 className="text-xl font-semibold">{step.title}</h2>
+            <p className="text-muted-foreground text-sm">{step.body}</p>
+          </article>
+        ))}
+      </section>
+      <section className="space-y-2">
+        <h2 className="text-2xl font-semibold">Audit trail</h2>
+        <p className="text-muted-foreground text-sm">
+          Every decrypt operation logs who requested it, what integration was
+          involved, and the purpose (sync, deploy, manual action).
+        </p>
+        <p className="text-muted-foreground text-sm">
+          You can stream audit logs to your SIEM via webhooks or export CSVs for
+          compliance reviews.
+        </p>
+      </section>
+    </main>
+  );
+}

package/src/components/docs/studio/StudioDeploymentsPage.tsx

@@ -0,0 +1,76 @@
+// export const metadata: Metadata = {
+//   title: 'Studio – Deployment Guide',
+//   description:
+//     'Learn how Studio provisions shared and dedicated environments, monitors health, and rolls back safely.',
+// };
+
+const comparisons = [
+  {
+    label: 'Shared',
+    points: [
+      'Ready in seconds',
+      'DEV + STAGE by default',
+      'Best for prototypes',
+      'Managed SSL',
+    ],
+  },
+  {
+    label: 'Dedicated',
+    points: [
+      'Isolated clusters',
+      'Choose region + VPC',
+      'Rolling deploys',
+      'Custom observability sinks',
+    ],
+  },
+];
+
+const checklist = [
+  'Validate specs before deploying (Studio does this automatically).',
+  'Tag deployments with a description so rituals have context.',
+  'Monitor status cards—failed deploys trigger alerts and auto rollback.',
+  'Use the CLI to export deployment manifests if you want infra-as-code.',
+];
+
+export function StudioDeploymentsPage() {
+  return (
+    <main className="space-y-12 py-12">
+      <header className="space-y-3">
+        <p className="text-xs font-semibold tracking-[0.3em] text-violet-400 uppercase">
+          Deployments
+        </p>
+        <h1 className="text-4xl font-bold">Shared vs dedicated workflows</h1>
+        <p className="text-muted-foreground max-w-3xl text-lg">
+          Studio abstracts infra, but you still stay in control. This guide
+          explains how environments are provisioned, monitored, and rolled back.
+        </p>
+      </header>
+      <section className="grid gap-4 md:grid-cols-2">
+        {comparisons.map((option) => (
+          <article key={option.label} className="card-subtle space-y-2 p-6">
+            <h2 className="text-2xl font-semibold">
+              {option.label} deployments
+            </h2>
+            <ul className="space-y-1 text-sm">
+              {option.points.map((point) => (
+                <li key={point}>• {point}</li>
+              ))}
+            </ul>
+          </article>
+        ))}
+      </section>
+      <section className="space-y-3">
+        <h2 className="text-2xl font-semibold">Health & rollback</h2>
+        <p className="text-muted-foreground text-sm">
+          Every deployment emits health events. If a check fails, Studio pauses
+          traffic and offers rollback controls with diff context.
+        </p>
+        <ul className="space-y-2 text-sm">
+          {checklist.map((item) => (
+            <li key={item}>• {item}</li>
+          ))}
+        </ul>
+      </section>
+    </main>
+  );
+}