// @bun
import l from"@contractspec/lib.ui-link";import{jsx as s,jsxs as p}from"react/jsx-runtime";function r({title:a="Need the operating layer on top of OSS ContractSpec?",body:n="ContractSpec Studio helps teams turn evidence into proposed spec changes, governed delivery loops, and execution-ready task packs while keeping the open contract system as the source of truth.",ctaLabel:c="See what Studio adds",href:d="https://www.contractspec.studio/docs"}){return p("div",{className:"card-subtle space-y-3 p-6",children:[s("h3",{className:"font-semibold text-lg",children:a}),s("p",{className:"text-muted-foreground text-sm",children:n}),s(l,{href:d,className:"btn-primary",children:c})]})}import{CodeBlock as i}from"@contractspec/lib.design-system";import o from"@contractspec/lib.ui-link";import{ChevronRight as m,Globe as u,Layers as y,Shield as f,Zap as h}from"lucide-react";import{jsx as e,jsxs as t}from"react/jsx-runtime";var b=[{name:"Operations",factory:"defineCommand / defineQuery",description:"API endpoints with input/output schemas, validation, and policy.",icon:h,color:"text-blue-400"},{name:"Events",factory:"defineEvent",description:"Domain events with typed payloads and PII handling.",icon:y,color:"text-green-400"},{name:"Capabilities",factory:"defineCapability",description:"Feature groupings that link operations, events, and UIs.",icon:f,color:"text-purple-400"},{name:"Presentations",factory:"definePresentation",description:"UI specifications for rendering data and handling interactions.",icon:u,color:"text-orange-400"}];function E(){return t("div",{className:"space-y-8",children:[t("div",{className:"space-y-3",children:[e("h1",{className:"font-bold text-4xl",children:"Contract Types Overview"}),e("p",{className:"text-lg text-muted-foreground",children:"Learn about the different contract types in ContractSpec and when to use each one when you are making the system boundary explicit."})]}),t("div",{className:"card-subtle space-y-4 p-6",children:[e("h2",{className:"font-bold text-2xl",children:"Core Contract Types"}),e("div",{className:"grid gap-3 md:grid-cols-2",children:b.map((a)=>t("div",{className:"flex items-start gap-3 rounded-lg border border-white/10 p-4",children:[e(a.icon,{className:a.color,size:20}),t("div",{className:"space-y-1",children:[e("h3",{className:"font-semibold",children:a.name}),e("p",{className:"text-muted-foreground text-xs",children:a.description}),e("code",{className:"text-violet-400 text-xs",children:a.factory})]})]},a.name))})]}),t("div",{className:"space-y-6",children:[t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"1) Operations (Commands & Queries)"}),e("p",{className:"text-muted-foreground text-sm",children:"Operations are the backbone of your API. Commands mutate state, queries read state. Both have typed input/output schemas."}),e(i,{language:"typescript",filename:"src/contracts/user.operation.ts",code:`import { defineCommand, defineQuery } from "@contractspec/lib.contracts-spec";
import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";

// Command: Mutates state (creates a user)
export const CreateUserCommand = defineCommand({
  meta: {
    key: "user.create",
    version: "1.0.0",
    description: "Create a new user account",
    stability: "stable",
    owners: ["platform.core"],
    tags: ["users", "auth"],
  },
  io: {
    input: new SchemaModel({
      name: "CreateUserInput",
      fields: {
        email: { type: ScalarTypeEnum.Email(), isOptional: false },
        name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
      },
    }),
    output: new SchemaModel({
      name: "CreateUserOutput",
      fields: {
        id: { type: ScalarTypeEnum.UUID(), isOptional: false },
        email: { type: ScalarTypeEnum.Email(), isOptional: false },
      },
    }),
    errors: {
      EMAIL_EXISTS: {
        description: "Email already registered",
        http: 409,
        when: "User with this email already exists",
      },
    },
  },
  policy: { auth: "admin" },
});

// Query: Reads state (gets user by ID)
export const GetUserQuery = defineQuery({
  meta: {
    key: "user.get",
    version: "1.0.0",
    description: "Get user by ID",
    stability: "stable",
    owners: ["platform.core"],
    tags: ["users"],
  },
  io: {
    input: new SchemaModel({
      name: "GetUserInput",
      fields: {
        id: { type: ScalarTypeEnum.UUID(), isOptional: false },
      },
    }),
    output: new SchemaModel({
      name: "GetUserOutput",
      fields: {
        id: { type: ScalarTypeEnum.UUID(), isOptional: false },
        email: { type: ScalarTypeEnum.Email(), isOptional: false },
        name: { type: ScalarTypeEnum.String(), isOptional: false },
      },
    }),
  },
  policy: { auth: "user" },
});`})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"2) Events"}),e("p",{className:"text-muted-foreground text-sm",children:"Events represent domain occurrences. They have typed payloads with PII field marking for compliance."}),e(i,{language:"typescript",filename:"src/contracts/user.event.ts",code:`import { defineEvent } from "@contractspec/lib.contracts-spec";
import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";

export const UserCreatedEvent = defineEvent({
  meta: {
    key: "user.created",
    version: "1.0.0",
    description: "Emitted when a new user is created",
    stability: "stable",
    owners: ["platform.core"],
    tags: ["users", "auth"],
  },
  // Mark PII fields for redaction in logs/exports
  pii: ["email"],
  payload: new SchemaModel({
    name: "UserCreatedPayload",
    fields: {
      userId: { type: ScalarTypeEnum.UUID(), isOptional: false },
      email: { type: ScalarTypeEnum.Email(), isOptional: false },
      createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
    },
  }),
});

export const UserDeletedEvent = defineEvent({
  meta: {
    key: "user.deleted",
    version: "1.0.0",
    description: "Emitted when a user is deleted",
    stability: "stable",
    owners: ["platform.core"],
    tags: ["users"],
  },
  payload: new SchemaModel({
    name: "UserDeletedPayload",
    fields: {
      userId: { type: ScalarTypeEnum.UUID(), isOptional: false },
      deletedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
      reason: { type: ScalarTypeEnum.String(), isOptional: true },
    },
  }),
});`})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"3) Capabilities"}),e("p",{className:"text-muted-foreground text-sm",children:"Capabilities group related operations, events, and presentations. They define feature boundaries and dependencies."}),e(i,{language:"typescript",filename:"src/contracts/user-management.capability.ts",code:`import { defineCapability } from "@contractspec/lib.contracts-spec";

export const UserManagementCapability = defineCapability({
  meta: {
    key: "user.management",
    version: "1.0.0",
    description: "User account management features",
    stability: "stable",
    owners: ["platform.core"],
    tags: ["users", "core"],
    kind: "api",
  },
  // Operations/events this capability provides
  provides: [
    { surface: "operation", key: "user.create", version: "1.0.0" },
    { surface: "operation", key: "user.get", version: "1.0.0" },
    { surface: "operation", key: "user.delete", version: "1.0.0" },
    { surface: "event", key: "user.created", version: "1.0.0" },
    { surface: "event", key: "user.deleted", version: "1.0.0" },
  ],
  // Dependencies on other capabilities
  requires: [
    { key: "auth.core", reason: "Needs authentication for user operations" },
  ],
});

// Capabilities can extend other capabilities
export const AdminUserCapability = defineCapability({
  meta: {
    key: "user.admin",
    version: "1.0.0",
    description: "Admin-only user management features",
    stability: "stable",
    owners: ["platform.core"],
    tags: ["users", "admin"],
    kind: "api",
  },
  // Inherit from base capability
  extends: { key: "user.management", version: "1.0.0" },
  provides: [
    { surface: "operation", key: "user.ban", version: "1.0.0" },
    { surface: "operation", key: "user.impersonate", version: "1.0.0" },
  ],
});`})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"4) Presentations"}),e("p",{className:"text-muted-foreground text-sm",children:"Presentations define UI specifications. They link to capabilities and specify how data should be displayed."}),e(i,{language:"typescript",filename:"src/contracts/user-list.presentation.ts",code:`import { definePresentation } from "@contractspec/lib.contracts-spec";

export const UserListPresentation = definePresentation({
  meta: {
    key: "users.list",
    version: "1.0.0",
    description: "Display a list of users with search and pagination",
    stability: "stable",
    owners: ["platform.core"],
    tags: ["users", "ui"],
  },
  // Link to capability that provides data
  capability: { key: "user.management", version: "1.0.0" },
  // UI specifications
  config: {
    title: "Users",
    layout: "table",
    columns: ["name", "email", "createdAt", "status"],
    actions: ["view", "edit", "delete"],
    pagination: { defaultPageSize: 25 },
    search: { fields: ["name", "email"] },
  },
});`})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"5) Additional Contract Types"}),e("p",{className:"text-muted-foreground text-sm",children:"ContractSpec provides specialized contracts for different concerns:"}),t("div",{className:"grid gap-4 md:grid-cols-2",children:[t("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Policy"}),e("code",{className:"text-violet-400 text-xs",children:"definePolicy"}),e("p",{className:"text-muted-foreground text-xs",children:"RBAC/ABAC rules, rate limits, and access control."})]}),t("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Workflow"}),e("code",{className:"text-violet-400 text-xs",children:"defineWorkflow"}),e("p",{className:"text-muted-foreground text-xs",children:"Multi-step processes with states, transitions, and SLAs."})]}),t("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Translation"}),e("code",{className:"text-violet-400 text-xs",children:"defineTranslation"}),e("p",{className:"text-muted-foreground text-xs",children:"i18n messages with ICU format and locale fallbacks."})]}),t("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Integration"}),e("code",{className:"text-violet-400 text-xs",children:"defineIntegration"}),e("p",{className:"text-muted-foreground text-xs",children:"External service connections and API adapters."})]}),t("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Form"}),e("code",{className:"text-violet-400 text-xs",children:"defineFormSpec"}),e("p",{className:"text-muted-foreground text-xs",children:"Form definitions with fields, validation, and layouts."})]}),t("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Data View"}),e("code",{className:"text-violet-400 text-xs",children:"defineDataView"}),e("p",{className:"text-muted-foreground text-xs",children:"Read-only data projections and aggregations."})]}),t("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Feature"}),e("code",{className:"text-violet-400 text-xs",children:"defineFeature"}),e("p",{className:"text-muted-foreground text-xs",children:"Feature flags and progressive rollout configurations."})]}),t("div",{className:"card-subtle space-y-2 p-4",children:[e("h3",{className:"font-semibold",children:"Test"}),e("code",{className:"text-violet-400 text-xs",children:"defineTestSpec"}),e("p",{className:"text-muted-foreground text-xs",children:"Contract-driven test scenarios and fixtures."})]})]})]}),t("div",{className:"space-y-3",children:[e("h2",{className:"font-bold text-2xl",children:"6) Registering Contracts"}),e("p",{className:"text-muted-foreground text-sm",children:"Each contract type has a registry for lookup and validation."}),e(i,{language:"typescript",filename:"src/contracts/registry.ts",code:`import {
  OperationSpecRegistry,
  installOp,
} from "@contractspec/lib.contracts-spec/operations";
import { EventRegistry } from "@contractspec/lib.contracts-spec";
import { CapabilityRegistry } from "@contractspec/lib.contracts-spec/capabilities";

// Import your contracts
import { CreateUserCommand, GetUserQuery } from "./user.operation";
import { UserCreatedEvent } from "./user.event";
import { UserManagementCapability } from "./user-management.capability";

// Create registries
export const operationRegistry = new OperationSpecRegistry();
export const eventRegistry = new EventRegistry();
export const capabilityRegistry = new CapabilityRegistry();

// Register operations with handlers
installOp(operationRegistry, CreateUserCommand, async (input) => {
  // Your implementation here
  return { id: "uuid", email: input.email };
});

installOp(operationRegistry, GetUserQuery, async (input) => {
  // Your implementation here
  return { id: input.id, email: "user@example.com", name: "User" };
});

// Register events and capabilities
eventRegistry.register(UserCreatedEvent);
capabilityRegistry.register(UserManagementCapability);`})]}),t("div",{className:"card-subtle space-y-3 p-6",children:[e("h3",{className:"font-semibold text-lg",children:"Contract Type Decision Guide"}),t("table",{className:"w-full text-sm",children:[e("thead",{children:t("tr",{className:"border-white/10 border-b",children:[e("th",{className:"py-2 text-left",children:"When you need..."}),e("th",{className:"py-2 text-left",children:"Use this contract"})]})}),t("tbody",{className:"text-muted-foreground",children:[t("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2",children:"An API endpoint that changes data"}),e("td",{className:"py-2",children:e("code",{children:"defineCommand"})})]}),t("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2",children:"An API endpoint that reads data"}),e("td",{className:"py-2",children:e("code",{children:"defineQuery"})})]}),t("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2",children:"Async notification of something that happened"}),e("td",{className:"py-2",children:e("code",{children:"defineEvent"})})]}),t("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2",children:"Group related specs under a feature"}),e("td",{className:"py-2",children:e("code",{children:"defineCapability"})})]}),t("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2",children:"Define UI rendering specifications"}),e("td",{className:"py-2",children:e("code",{children:"definePresentation"})})]}),t("tr",{className:"border-white/5 border-b",children:[e("td",{className:"py-2",children:"Access control and rate limiting"}),e("td",{className:"py-2",children:e("code",{children:"definePolicy"})})]}),t("tr",{children:[e("td",{className:"py-2",children:"Multi-step business processes"}),e("td",{className:"py-2",children:e("code",{children:"defineWorkflow"})})]})]})]})]}),e(r,{title:"Need to decide which contract should change next?",body:"Studio uses evidence and focus constraints to generate decision briefs, patch intents, and execution-ready task packs."})]}),t("div",{className:"flex items-center gap-4 pt-4",children:[t(o,{href:"/docs/guides/nextjs-one-endpoint",className:"btn-primary",children:["Next: Add your first endpoint ",e(m,{size:16})]}),e(o,{href:"/docs/guides",className:"btn-ghost",children:"Back to guides"})]})]})}export{E as GuideContractTypesPage};
