@claudetools/tools 0.8.10 → 0.9.0

package/docs/research/2026-01-02-kappa-v2.5-specification.md

@@ -0,0 +1,1218 @@
+# Kappa v2.5: The Practical Specification Language
+
+**Date:** 2026-01-02
+**Status:** CodeDNA Foundation Spec
+**Philosophy:** Novel enough to matter. Practical enough to ship.
+
+---
+
+## Part I: Design Principles
+
+### 1.1 What We Keep (Novel + Buildable)
+
+| Feature | Why It's Novel | Why It's Buildable |
+|---------|---------------|-------------------|
+| Entity Capabilities | `can:` / `cannot:` replace scattered permission logic | Maps directly to middleware/guards |
+| Lifecycle Hooks | `on_create:`, `on_delete:` are declarative | Generates event handlers |
+| Journeys | User flows as first-class, not route derivatives | State machine generators exist |
+| Effect Annotations | `-[DB, Auth]->` declares side effects | Generates middleware chains |
+| Provenance | Every line traces to spec | Comment generation |
+| Rich Field Constraints | `string(2..100)`, `email`, `unique` | Zod/Valibot schemas |
+
+### 1.2 What We Drop (Research Territory)
+
+| Feature | Why We Drop It |
+|---------|---------------|
+| Constraint Solver | Unbounded synthesis is research, not engineering |
+| Mood → Design | Requires AI inference, non-deterministic |
+| Bidirectional Sync | Every attempt at this has failed at scale |
+| Goal Inference | "ensure: no duplicate accounts" needs AI to interpret |
+| Learning System | Pattern extraction is ML research |
+
+### 1.3 The Core Insight
+
+**Kappa v2.5 is a high-level DSL that compiles to code via generators.**
+
+```
+Kappa Spec → Parser → AST → Generator(framework) → Code
+```
+
+No AI in the loop. No constraint solving. Deterministic compilation.
+
+The AI writes the Kappa spec. The generator produces the code. Separation of concerns.
+
+---
+
+## Part II: Language Specification
+
+### 2.1 Project Declaration
+
+```kappa
+project TaskFlow {
+  version: "1.0.0"
+  stack: tanstack-start | next | remix | express
+  database: postgres | mysql | sqlite | turso
+  auth: jwt | session | oauth
+  ui: shadcn | mui | chakra | tailwind-only
+}
+```
+
+**Generator behavior:** Stack choice selects generator. All other options configure it.
+
+---
+
+### 2.2 Auth Block
+
+```kappa
+auth jwt {
+  secret: env(JWT_SECRET)
+  issuer: "taskflow.app"
+  audience: "taskflow-api"
+  expires: 7d
+  refresh: sliding | fixed | none
+
+  hash: argon2id {
+    memory: 64mb
+    iterations: 3
+    parallelism: 1
+  }
+
+  # Or shorthand
+  hash: argon2id(memory: 64mb, iterations: 3)
+
+  # Or bcrypt
+  hash: bcrypt(rounds: 12)
+}
+```
+
+**Generates:**
+- `lib/auth.ts` - JWT sign/verify, password hashing
+- `middleware/auth.ts` - requireAuth, optionalAuth
+- Session management if `refresh: sliding`
+
+---
+
+### 2.3 Entity Block
+
+Entities are the core data model with capabilities and lifecycle.
+
+```kappa
+entity User {
+  # === FIELDS ===
+  id: uuid, primary, auto
+  email: email, unique, immutable
+  name: string(2..100)
+  password: string, hashed, internal  # never exposed in API
+  role: admin | member | guest = member
+  avatar: url?
+  created_at: timestamp, auto
+  updated_at: timestamp, auto, on_update
+
+  # === RELATIONSHIPS ===
+  has_many: Project (as owner, cascade: nullify)
+  has_many: Membership
+  has_many: Team (through: Membership)
+
+  # === CAPABILITIES ===
+  can: [
+    create Project,
+    read Project (where: member_of),
+    update Project (where: owner_of),
+    delete Project (where: owner_of),
+    invite User (to: Team, where: admin_of)
+  ]
+
+  cannot: [
+    delete self (unless: no_owned_projects),
+    change role (unless: admin)
+  ]
+
+  # === LIFECYCLE ===
+  on_create: [
+    send_email(template: welcome),
+    log_audit(action: user_created),
+    enqueue(job: sync_to_crm)
+  ]
+
+  on_update(email): [
+    send_email(template: email_changed, to: old.email),
+    require_reverification
+  ]
+
+  on_delete: [
+    anonymize(fields: [email, name]),
+    transfer_ownership(to: system_user),
+    log_audit(action: user_deleted)
+  ]
+
+  # === INDEXES ===
+  index: [email]
+  index: [role, created_at]
+}
+```
+
+#### Field Modifiers
+
+| Modifier | Meaning | Generates |
+|----------|---------|-----------|
+| `primary` | Primary key | Schema primary key |
+| `unique` | Unique constraint | DB constraint + validation |
+| `auto` | Auto-generated | Default value / trigger |
+| `immutable` | Cannot be changed after creation | Update validation |
+| `internal` | Never exposed in API responses | DTO exclusion |
+| `hashed` | Stored as hash | Hash on write, verify on read |
+| `?` suffix | Optional/nullable | Optional in schema |
+| `= value` | Default value | Schema default |
+
+#### Field Types
+
+```kappa
+# Primitives
+string                    # Any string
+string(10)                # Exactly 10 chars
+string(2..100)            # 2-100 chars
+string(..500)             # Max 500 chars
+int                       # Integer
+int(0..100)               # Range constraint
+float                     # Decimal
+bool                      # Boolean
+
+# Semantic Types (with built-in validation)
+email                     # Valid email format
+url                       # Valid URL
+uuid                      # UUID v4
+phone                     # Phone number (E.164)
+slug                      # URL-safe string
+markdown                  # Markdown content
+json                      # Arbitrary JSON
+
+# Temporal
+timestamp                 # DateTime
+date                      # Date only
+time                      # Time only
+duration                  # Time duration
+
+# Enums (inline)
+status: draft | published | archived
+
+# References
+owner: -> User            # Foreign key
+owner: -> User?           # Optional foreign key
+```
+
+---
+
+### 2.4 API Block
+
+Define API operations with effects.
+
+```kappa
+api Users {
+  # === AUTH ENDPOINTS ===
+
+  signup: (
+    email: email,
+    password: string(8..),
+    name: string(2..100)
+  ) -[DB, Email, Audit]-> User
+    throws: EmailTaken, WeakPassword
+    rate_limit: 5/minute
+
+  login: (
+    email: email,
+    password: string
+  ) -[DB, Auth]-> { user: User, token: string }
+    throws: InvalidCredentials
+    rate_limit: 10/minute
+    audit: always
+
+  logout: () -[Auth]-> void
+
+  me: () -[Auth]-> User
+
+  # === CRUD (shorthand) ===
+
+  crud Project {
+    create: -[Auth, DB]-> Project
+    read: -[Auth, DB]-> Project
+    update: -[Auth, DB]-> Project (check: owner_of)
+    delete: -[Auth, DB]-> void (check: owner_of)
+    list: -[Auth, DB]-> [Project] (filter: member_of)
+  }
+
+  # === CUSTOM OPERATIONS ===
+
+  invite_to_project: (
+    project_id: uuid,
+    email: email,
+    role: owner | editor | viewer = viewer
+  ) -[Auth, DB, Email]-> Invitation
+    check: owner_of(project_id)
+    throws: AlreadyMember, ProjectNotFound
+}
+```
+
+#### Effect Annotations
+
+| Effect | Meaning | Generates |
+|--------|---------|-----------|
+| `DB` | Database access | Transaction wrapper |
+| `Auth` | Requires authentication | Auth middleware |
+| `Email` | Sends email | Email service call |
+| `Audit` | Audit logging | Audit log entry |
+| `Queue` | Background job | Queue enqueue |
+| `Cache` | Uses cache | Cache read/write |
+| `External` | External API call | HTTP client |
+
+#### API Modifiers
+
+| Modifier | Meaning |
+|----------|---------|
+| `throws: Error1, Error2` | Possible errors (generates error types) |
+| `check: permission` | Capability check before execution |
+| `rate_limit: N/period` | Rate limiting |
+| `audit: always \| on_error \| never` | Audit logging behavior |
+| `cache: duration` | Response caching |
+| `deprecated: "message"` | Marks as deprecated |
+
+---
+
+### 2.5 Journey Block
+
+User journeys are first-class. Not derived from routes.
+
+```kappa
+journey Onboarding {
+  actor: new_user
+
+  # === STEPS ===
+  steps {
+    signup {
+      page: SignupForm
+      action: api.signup
+      next: verify_email
+      on_error: show_error, stay
+    }
+
+    verify_email {
+      page: VerifyEmail
+      wait_for: email_verified
+      timeout: 24h -> resend_or_cancel
+      next: create_workspace
+    }
+
+    create_workspace {
+      page: WorkspaceSetup
+      action: api.create_workspace
+      next: invite_team
+      skip_if: joining_existing_workspace
+    }
+
+    invite_team {
+      page: InviteTeam
+      action: api.send_invites
+      next: ready
+      skippable: true
+    }
+
+    ready {
+      page: Dashboard
+      complete: true
+    }
+  }
+
+  # === ANALYTICS ===
+  track: [step_entered, step_completed, step_skipped, journey_completed]
+
+  # === RECOVERY ===
+  on_abandon(verify_email): send_reminder(after: 1h, max: 3)
+  on_abandon(create_workspace): send_help_email(after: 24h)
+}
+```
+
+**Generates:**
+- State machine for journey progression
+- Route guards ensuring step order
+- Analytics events
+- Recovery job scheduling
+- Progress persistence
+
+---
+
+### 2.6 Page Block
+
+Pages with data loading and layout.
+
+```kappa
+page Dashboard {
+  route: "/dashboard"
+  guard: authenticated
+
+  # === DATA ===
+  load {
+    projects: api.list_projects()
+    user: api.me()
+    notifications: api.notifications(unread: true, limit: 5)
+  }
+
+  # === LAYOUT ===
+  layout: AppShell {
+    header: Navbar(user: user, notifications: notifications)
+    sidebar: ProjectList(projects: projects)
+    content: ProjectGrid(projects: projects)
+  }
+
+  # === ACTIONS ===
+  actions {
+    create_project: modal(CreateProjectForm) -> api.create_project -> refresh
+    mark_notification_read: api.mark_read -> refresh(notifications)
+  }
+
+  # === META ===
+  title: "Dashboard | TaskFlow"
+  meta: { description: "Your projects and tasks" }
+}
+```
+
+---
+
+### 2.7 Component Block
+
+Reusable UI components.
+
+```kappa
+component ProjectCard {
+  props {
+    project: Project
+    onEdit: () -> void
+    onDelete: () -> void
+  }
+
+  # === STRUCTURE ===
+  structure: card {
+    header {
+      title: project.name
+      badge: project.status
+      menu: [
+        item("Edit", onClick: onEdit, icon: edit),
+        item("Delete", onClick: onDelete, icon: trash, variant: danger)
+      ]
+    }
+
+    body {
+      text: project.description ?? "No description"
+      meta: [
+        item(icon: calendar, value: format_date(project.created_at)),
+        item(icon: users, value: project.member_count)
+      ]
+    }
+
+    footer {
+      avatar_group: project.members (max: 3)
+      link: "/projects/{project.id}"
+    }
+  }
+
+  # === VARIANTS ===
+  variants {
+    compact: hide(body.meta, footer.avatar_group)
+    minimal: only(header.title, footer.link)
+  }
+}
+```
+
+#### Compound Component Pattern
+
+```kappa
+component DataTable {
+  props {
+    data: [T]
+    columns: [Column<T>]
+  }
+
+  compound {
+    Root: table_container
+    Header: thead
+    HeaderRow: tr
+    HeaderCell: th (sortable?, filterable?)
+    Body: tbody
+    Row: tr (selectable?, expandable?)
+    Cell: td
+    Pagination: nav
+    Empty: empty_state
+    Loading: skeleton
+  }
+
+  # Usage composes the compound parts
+  default_composition {
+    Root {
+      Header {
+        HeaderRow {
+          for column in columns: HeaderCell(column)
+        }
+      }
+      Body {
+        for row in data: Row {
+          for column in columns: Cell(row[column.key])
+        }
+      }
+      Pagination(total: data.length)
+    }
+  }
+}
+```
+
+---
+
+### 2.8 Form Block
+
+Forms with validation and submission.
+
+```kappa
+form CreateProject {
+  # === FIELDS ===
+  fields {
+    name: text {
+      label: "Project Name"
+      placeholder: "My Awesome Project"
+      validate: string(2..100)
+      required: true
+    }
+
+    description: textarea {
+      label: "Description"
+      placeholder: "What's this project about?"
+      validate: string(..1000)
+      rows: 4
+    }
+
+    visibility: select {
+      label: "Visibility"
+      options: [
+        { value: "private", label: "Private", icon: lock },
+        { value: "team", label: "Team", icon: users },
+        { value: "public", label: "Public", icon: globe }
+      ]
+      default: "private"
+    }
+
+    template: select {
+      label: "Template"
+      options: from(api.list_templates)
+      searchable: true
+      optional: true
+    }
+  }
+
+  # === SUBMIT ===
+  submit {
+    action: api.create_project
+    button: "Create Project"
+    loading: "Creating..."
+    on_success: navigate("/projects/{result.id}")
+    on_error: toast.error(error.message)
+  }
+
+  # === LAYOUT ===
+  layout: stack(gap: 4) {
+    row { name }
+    row { description }
+    row(columns: 2) { visibility, template }
+  }
+}
+```
+
+---
+
+### 2.9 Design Block
+
+Explicit design tokens. No mood interpretation.
+
+```kappa
+design {
+  # === COLORS ===
+  colors {
+    primary: #3B82F6
+    primary_hover: darken(primary, 10%)
+    primary_foreground: #FFFFFF
+
+    secondary: #6B7280
+    accent: #8B5CF6
+
+    background: #FFFFFF
+    foreground: #111827
+    muted: #F3F4F6
+    muted_foreground: #6B7280
+
+    success: #10B981
+    warning: #F59E0B
+    error: #EF4444
+    info: #3B82F6
+
+    # Dark mode overrides
+    dark {
+      background: #111827
+      foreground: #F9FAFB
+      muted: #1F2937
+      muted_foreground: #9CA3AF
+    }
+  }
+
+  # === TYPOGRAPHY ===
+  typography {
+    font_family: "Inter, system-ui, sans-serif"
+    font_mono: "JetBrains Mono, monospace"
+
+    scale {
+      xs: 0.75rem
+      sm: 0.875rem
+      base: 1rem
+      lg: 1.125rem
+      xl: 1.25rem
+      2xl: 1.5rem
+      3xl: 1.875rem
+      4xl: 2.25rem
+    }
+
+    weight {
+      normal: 400
+      medium: 500
+      semibold: 600
+      bold: 700
+    }
+  }
+
+  # === SPACING ===
+  spacing {
+    unit: 4px
+    scale: [0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 64]
+  }
+
+  # === BORDERS ===
+  borders {
+    radius {
+      none: 0
+      sm: 0.125rem
+      default: 0.25rem
+      md: 0.375rem
+      lg: 0.5rem
+      xl: 0.75rem
+      full: 9999px
+    }
+
+    width: 1px
+    color: muted
+  }
+
+  # === SHADOWS ===
+  shadows {
+    sm: "0 1px 2px rgba(0, 0, 0, 0.05)"
+    default: "0 1px 3px rgba(0, 0, 0, 0.1)"
+    md: "0 4px 6px rgba(0, 0, 0, 0.1)"
+    lg: "0 10px 15px rgba(0, 0, 0, 0.1)"
+    xl: "0 20px 25px rgba(0, 0, 0, 0.1)"
+  }
+
+  # === MOTION ===
+  motion {
+    duration {
+      fast: 150ms
+      default: 200ms
+      slow: 300ms
+    }
+
+    easing {
+      default: cubic-bezier(0.4, 0, 0.2, 1)
+      in: cubic-bezier(0.4, 0, 1, 1)
+      out: cubic-bezier(0, 0, 0.2, 1)
+    }
+  }
+}
+```
+
+**Generates:**
+- CSS custom properties
+- Tailwind config
+- Theme provider
+- Dark mode toggle
+
+---
+
+## Part III: Provenance Tracking
+
+Every generated line includes its origin.
+
+### 3.1 Provenance Comments
+
+```typescript
+// Generated from: entity User > field email
+// Spec: email: email, unique, immutable
+export const users = pgTable('users', {
+  // ...
+  email: text('email').notNull().unique(),
+  // ...
+});
+
+// Generated from: entity User > on_create
+// Spec: send_email(template: welcome)
+async function onUserCreate(user: User) {
+  await emailService.send({
+    to: user.email,
+    template: 'welcome',  // from: on_create > send_email > template
+  });
+}
+
+// Generated from: entity User > can > create Project
+// Spec: can: create Project
+export function canCreateProject(user: User): boolean {
+  return true; // All authenticated users can create projects
+}
+
+// Generated from: entity User > cannot > delete self
+// Spec: cannot: delete self (unless: no_owned_projects)
+export async function canDeleteSelf(user: User): Promise<boolean> {
+  const ownedProjects = await db.query.projects.findMany({
+    where: eq(projects.ownerId, user.id)
+  });
+  return ownedProjects.length === 0;
+}
+```
+
+### 3.2 Source Maps
+
+```json
+{
+  "src/db/schema.ts": {
+    "lines": {
+      "15-20": { "source": "entity User", "spec_line": 12 },
+      "22": { "source": "entity User > field email", "spec_line": 14 }
+    }
+  },
+  "src/lib/permissions.ts": {
+    "lines": {
+      "8-12": { "source": "entity User > can", "spec_line": 28 }
+    }
+  }
+}
+```
+
+### 3.3 Why This Matters
+
+When debugging, developers can:
+1. See exactly what spec produced this code
+2. Navigate from code → spec
+3. Understand why a permission exists
+4. Trace business logic to requirements
+
+---
+
+## Part IV: Generator Architecture
+
+### 4.1 Pipeline
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        KAPPA SPEC                                │
+│  (entities, apis, journeys, pages, components, design)          │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                         PARSER                                   │
+│  - Tokenizer                                                     │
+│  - AST Builder                                                   │
+│  - Semantic Validation                                           │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      KAPPA AST                                   │
+│  Fully validated, typed abstract syntax tree                    │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    GENERATOR SELECTOR                            │
+│  project.stack → selects framework generator                     │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+           ┌──────────────────┼──────────────────┐
+           ▼                  ▼                  ▼
+    ┌────────────┐     ┌────────────┐     ┌────────────┐
+    │ TanStack   │     │ Next.js    │     │ Express    │
+    │ Generator  │     │ Generator  │     │ Generator  │
+    └────────────┘     └────────────┘     └────────────┘
+           │                  │                  │
+           └──────────────────┼──────────────────┘
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     GENERATED CODE                               │
+│  - Database schema                                               │
+│  - API routes                                                    │
+│  - Auth middleware                                               │
+│  - UI components                                                 │
+│  - Pages with loaders                                            │
+│  - Permissions                                                   │
+│  - Design tokens                                                 │
+│  - Provenance source maps                                        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 4.2 Generator Interface
+
+```typescript
+interface KappaGenerator {
+  name: string;
+  version: string;
+
+  // Generate all outputs from AST
+  generate(ast: KappaAST, options: GeneratorOptions): GeneratorOutput;
+
+  // Individual generators (for incremental updates)
+  generateSchema(entities: EntityNode[]): FileOutput[];
+  generateAPI(apis: APINode[]): FileOutput[];
+  generateAuth(auth: AuthNode): FileOutput[];
+  generatePages(pages: PageNode[]): FileOutput[];
+  generateComponents(components: ComponentNode[]): FileOutput[];
+  generateDesign(design: DesignNode): FileOutput[];
+  generateJourneys(journeys: JourneyNode[]): FileOutput[];
+}
+
+interface GeneratorOutput {
+  files: FileOutput[];
+  sourceMap: SourceMap;
+  warnings: Warning[];
+}
+
+interface FileOutput {
+  path: string;
+  content: string;
+  provenance: ProvenanceInfo[];
+}
+```
+
+### 4.3 Template System
+
+Generators use templates with slots:
+
+```typescript
+// Template: api-route.ts.template
+const template = `
+// Generated from: {{provenance}}
+import { createAPIFileRoute } from '@tanstack/start/api';
+{{#if hasValidation}}
+import { z } from 'zod';
+{{/if}}
+{{#if hasAuth}}
+import { requireAuth } from '~/lib/auth';
+{{/if}}
+import { db } from '~/db';
+
+{{#each schemas}}
+const {{name}}Schema = {{zodSchema}};
+{{/each}}
+
+export const APIRoute = createAPIFileRoute('{{routePath}}')({
+  {{#each methods}}
+  {{method}}: async ({ request }) => {
+    {{#if requiresAuth}}
+    const user = await requireAuth(request);
+    {{/if}}
+
+    {{#if hasBody}}
+    const body = {{schema}}Schema.parse(await request.json());
+    {{/if}}
+
+    {{> methodBody}}
+
+    return Response.json({ data: result });
+  },
+  {{/each}}
+});
+`;
+```
+
+---
+
+## Part V: Complete Example
+
+### 5.1 TaskFlow Spec
+
+```kappa
+project TaskFlow {
+  version: "1.0.0"
+  stack: tanstack-start
+  database: turso
+  auth: jwt
+  ui: shadcn
+}
+
+# === AUTH ===
+
+auth jwt {
+  secret: env(JWT_SECRET)
+  expires: 7d
+  refresh: sliding
+  hash: argon2id(memory: 64mb, iterations: 3)
+}
+
+# === ENTITIES ===
+
+entity User {
+  id: uuid, primary, auto
+  email: email, unique, immutable
+  name: string(2..100)
+  password: string, hashed, internal
+  avatar: url?
+  role: admin | member = member
+  created_at: timestamp, auto
+
+  has_many: Project (as owner)
+  has_many: Membership
+  has_many: Team (through: Membership)
+
+  can: [
+    create Project,
+    read Project (where: member_of),
+    update Project (where: owner_of),
+    delete Project (where: owner_of)
+  ]
+
+  on_create: send_email(template: welcome)
+}
+
+entity Project {
+  id: uuid, primary, auto
+  name: string(2..100)
+  description: string(..1000)?
+  status: active | archived = active
+  owner: -> User
+  created_at: timestamp, auto
+  updated_at: timestamp, auto, on_update
+
+  has_many: Task
+  has_many: Membership
+  has_many: User (through: Membership, as: members)
+
+  index: [owner, status]
+}
+
+entity Task {
+  id: uuid, primary, auto
+  title: string(2..200)
+  description: markdown?
+  status: todo | in_progress | done = todo
+  priority: low | medium | high = medium
+  due_date: date?
+  project: -> Project
+  assignee: -> User?
+  created_at: timestamp, auto
+
+  index: [project, status]
+  index: [assignee, status]
+}
+
+entity Membership {
+  user: -> User, primary
+  project: -> Project, primary
+  role: owner | editor | viewer
+  joined_at: timestamp, auto
+}
+
+# === API ===
+
+api Auth {
+  signup: (email: email, password: string(8..), name: string(2..100))
+    -[DB, Email]-> User
+    throws: EmailTaken
+    rate_limit: 5/minute
+
+  login: (email: email, password: string)
+    -[DB, Auth]-> { user: User, token: string }
+    throws: InvalidCredentials
+    rate_limit: 10/minute
+
+  logout: () -[Auth]-> void
+  me: () -[Auth]-> User
+}
+
+api Projects {
+  crud Project {
+    create: -[Auth, DB]-> Project
+    read: -[Auth, DB]-> Project (check: member_of)
+    update: -[Auth, DB]-> Project (check: owner_of)
+    delete: -[Auth, DB]-> void (check: owner_of)
+    list: -[Auth, DB]-> [Project] (filter: member_of)
+  }
+}
+
+api Tasks {
+  crud Task {
+    create: -[Auth, DB]-> Task (scope: project)
+    read: -[Auth, DB]-> Task
+    update: -[Auth, DB]-> Task
+    delete: -[Auth, DB]-> void
+    list: -[Auth, DB]-> [Task] (scope: project)
+  }
+
+  assign: (task_id: uuid, user_id: uuid?)
+    -[Auth, DB]-> Task
+
+  move: (task_id: uuid, status: string)
+    -[Auth, DB]-> Task
+}
+
+# === JOURNEY ===
+
+journey Onboarding {
+  actor: new_user
+
+  steps {
+    signup { page: SignupForm, action: Auth.signup, next: create_project }
+    create_project { page: CreateProjectForm, action: Projects.create, next: dashboard }
+    dashboard { page: Dashboard, complete: true }
+  }
+}
+
+# === PAGES ===
+
+page Login {
+  route: "/login"
+  guard: guest_only
+  component: LoginForm
+  title: "Login | TaskFlow"
+}
+
+page Dashboard {
+  route: "/dashboard"
+  guard: authenticated
+
+  load {
+    projects: Projects.list()
+    user: Auth.me()
+  }
+
+  layout: AppShell {
+    content: ProjectGrid(projects)
+  }
+
+  title: "Dashboard | TaskFlow"
+}
+
+page ProjectDetail {
+  route: "/projects/:id"
+  guard: authenticated
+
+  load {
+    project: Projects.read(params.id)
+    tasks: Tasks.list(project_id: params.id)
+  }
+
+  layout: AppShell {
+    content: TaskBoard(project, tasks)
+  }
+
+  title: "{project.name} | TaskFlow"
+}
+
+# === DESIGN ===
+
+design {
+  colors {
+    primary: #3B82F6
+    background: #FFFFFF
+    foreground: #111827
+
+    dark {
+      background: #111827
+      foreground: #F9FAFB
+    }
+  }
+
+  typography {
+    font_family: "Inter, system-ui, sans-serif"
+  }
+
+  borders {
+    radius { default: 0.5rem }
+  }
+}
+```
+
+### 5.2 Generated Output
+
+**Total Kappa spec:** ~200 lines (~800 tokens)
+
+**Generated files:**
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `db/schema.ts` | 85 | Drizzle schema |
+| `db/migrations/001_init.sql` | 60 | SQL migration |
+| `lib/auth.ts` | 95 | JWT + Argon2 |
+| `middleware/auth.ts` | 45 | Auth guards |
+| `lib/permissions.ts` | 80 | Capability checks |
+| `api/auth.ts` | 120 | Auth endpoints |
+| `api/projects.ts` | 150 | Project CRUD |
+| `api/tasks.ts` | 180 | Task CRUD + actions |
+| `routes/login.tsx` | 90 | Login page |
+| `routes/dashboard.tsx` | 120 | Dashboard page |
+| `routes/projects.$id.tsx` | 140 | Project detail |
+| `components/LoginForm.tsx` | 85 | Login form |
+| `components/ProjectGrid.tsx` | 75 | Project grid |
+| `components/TaskBoard.tsx` | 150 | Kanban board |
+| `lib/journey.ts` | 60 | Onboarding state |
+| `styles/tokens.css` | 80 | CSS custom props |
+| `tailwind.config.ts` | 45 | Tailwind config |
+
+**Total generated:** ~1,660 lines (~6,500 tokens)
+
+**Expansion ratio:** 8x
+
+---
+
+## Part VI: Why This Works
+
+### 6.1 Novel Enough
+
+| Feature | Status Quo | Kappa v2.5 |
+|---------|-----------|------------|
+| Permissions | Scattered guards/checks | `can:` / `cannot:` on entities |
+| User flows | Implicit in routes | Explicit `journey` blocks |
+| Field validation | Separate schema + validator | Inline `string(2..100)` |
+| Lifecycle | Event listeners somewhere | `on_create:` on entities |
+| Effects | Hidden in implementations | `-[DB, Auth]->` declared |
+| Provenance | None | Every line traces to spec |
+
+### 6.2 Practical Enough
+
+| Aspect | How We Stay Practical |
+|--------|---------------------|
+| Parsing | Standard recursive descent, no AI |
+| Validation | Type checking at parse time |
+| Generation | Template-based, deterministic |
+| Output | Standard framework code |
+| Tooling | LSP, syntax highlighting achievable |
+| Debugging | Source maps, provenance comments |
+
+### 6.3 The Sweet Spot
+
+```
+Expressiveness ◄──────────────────────────────► Practicality
+
+v1: Too simple ─────┐
+                    │
+v3: Too ambitious ──┼────────────────────────── Research territory
+                    │
+v2.5: ──────────────┴─── HERE ───────────────── Buildable, novel
+```
+
+---
+
+## Part VII: Implementation Roadmap
+
+### Phase 1: Core Language (4 weeks)
+
+- [ ] Lexer and parser
+- [ ] AST definition
+- [ ] Semantic validation
+- [ ] Error reporting with locations
+
+**Deliverable:** Parse Kappa specs, reject invalid ones.
+
+### Phase 2: Entity Generator (3 weeks)
+
+- [ ] Drizzle schema generation
+- [ ] Zod validation schemas
+- [ ] TypeScript types
+- [ ] Basic provenance comments
+
+**Deliverable:** `entity` blocks → working database layer.
+
+### Phase 3: API Generator (3 weeks)
+
+- [ ] TanStack Start API routes
+- [ ] CRUD operations from `crud` shorthand
+- [ ] Effect → middleware mapping
+- [ ] Permission checks from capabilities
+
+**Deliverable:** `api` blocks → working API endpoints.
+
+### Phase 4: Auth Generator (2 weeks)
+
+- [ ] JWT implementation from `auth jwt`
+- [ ] Password hashing from `hash:` config
+- [ ] Auth middleware
+- [ ] Session management
+
+**Deliverable:** `auth` block → complete auth system.
+
+### Phase 5: Page Generator (3 weeks)
+
+- [ ] Route generation with guards
+- [ ] Loader generation from `load` block
+- [ ] Layout composition
+- [ ] Component wiring
+
+**Deliverable:** `page` blocks → working pages with data.
+
+### Phase 6: Journey Generator (2 weeks)
+
+- [ ] State machine from journey steps
+- [ ] Step guards
+- [ ] Progress tracking
+- [ ] Recovery handlers
+
+**Deliverable:** `journey` blocks → guided user flows.
+
+### Phase 7: Design Generator (2 weeks)
+
+- [ ] CSS custom properties
+- [ ] Tailwind config
+- [ ] Theme provider
+- [ ] Dark mode
+
+**Deliverable:** `design` block → consistent styling.
+
+### Phase 8: Tooling (3 weeks)
+
+- [ ] VSCode extension (syntax highlighting)
+- [ ] LSP for autocomplete/errors
+- [ ] Source map viewer
+- [ ] CLI tool
+
+**Deliverable:** First-class editor experience.
+
+**Total: ~22 weeks** to full v2.5 implementation.
+
+---
+
+## Part VIII: Success Metrics
+
+### For AI Code Generation
+
+| Metric | Target |
+|--------|--------|
+| Token reduction | 80%+ (spec vs generated) |
+| Correctness | 95%+ (generates valid, runnable code) |
+| Completeness | One spec → full feature |
+
+### For Developer Experience
+
+| Metric | Target |
+|--------|--------|
+| Learning curve | < 1 hour to productivity |
+| Spec readability | Non-technical stakeholders can review |
+| Debug time | 50% reduction via provenance |
+
+### For CodeDNA
+
+| Metric | Target |
+|--------|--------|
+| Cost per feature | 90%+ reduction vs manual AI prompting |
+| Consistency | Same spec → same output |
+| Extensibility | New generators < 1 week to add |
+
+---
+
+*Kappa v2.5: Write what you mean. Generate what you need.*