IVP Compliance Review: CodeAI - An AI-Designed Language Evaluated Against the Independent Variation Principle

AI disclosure: This article was generated by Claude Sonnet 4.5.

Executive Summary

This document presents a formal architectural review of CodeAI, a domain-specific language designed by large language models for backend service declaration. The review evaluates the language against the Independent Variation Principle (IVP): the principle that each concern should vary in exactly one place.

Key Findings:

• ✅ Strong IVP Compliance: CodeAI demonstrates excellent concern separation at the language design level
• ✅ Seven Independent Syntactic Domains: Infrastructure, data schema (relational), data schema (document), API surface, events, integrations, workflows, and scheduled jobs each have distinct variation points
• ✅ Enforced Separation: The language syntax prevents concern entanglement through mandatory structural boundaries
• ⚠️ Implementation Context: Review based on v1.0 codebase examples; runtime implementation not evaluated

Verdict: CodeAI exhibits IVP-compliant design that actively guides developers toward maintainable, loosely-coupled system architectures.

---

1. Introduction

1.1 Context

On LinkedIn, Barış Gömeç announced an experiment: "I asked AI to design a programming language that AI understands better." The resulting language, CodeAI (.cai), is a declarative DSL for backend service definition, with the entire implementation generated by Claude Opus 4.5.

The creator's premise: simpler declarative syntax optimized for LLM code generation. This review adds a complementary architectural lens: Is the language also optimized for human maintainability through concern separation?

1.2 The Independent Variation Principle (IVP)

The Independent Variation Principle, as formally defined by Loth (2025), states:

"Separate elements with different change driver assignments into distinct units; unify elements with the same change driver assignment within a single unit."

A change driver is any source of variation in a system—a reason why code might need to change. A change driver assignment maps each element (function, class, module, file) to the set of change drivers that influence it. IVP prescribes that elements varying for the same reasons should be grouped together, while elements varying for different reasons should be separated.

IVP generalizes classical principles like Single Responsibility (SRP), Don't Repeat Yourself (DRY), and Separation of Concerns (SoC) by providing a unified framework based on independent variability. It extends Parnas's information hiding criterion by making change drivers explicit.

IVP Compliance Criteria:

1. Identification: Can distinct change drivers be clearly identified?
2. Localization: Does each change driver have a single, well-defined unit where it varies?
3. Independence: Can one change driver change without forcing changes to units governed by different change drivers?
4. Non-Repetition: Is each change driver assignment expressed exactly once?

1.2.1 The Role of Programming Languages in IVP

A well-designed programming language should help developers achieve IVP compliance through its syntactic and semantic structure. Language design influences architectural quality by:

1. Providing Appropriate Abstractions: Offering constructs that map naturally to distinct change drivers (e.g., separate syntax for data schema vs. business logic)
2. Enforcing Boundaries: Making it syntactically impossible or awkward to mix concerns that should vary independently
3. Guiding Composition: Enabling references between concerns without requiring embedding (composition over containment)
4. Encoding Architectural Intent: Making the separation of concerns visible and explicit in the code structure

Languages that conflate multiple change drivers into single constructs (e.g., OOP classes mixing schema, validation, business logic, and persistence) make IVP compliance harder. Developers must fight against the language's default organization. Conversely, languages with distinct syntactic spaces for distinct concerns (like CodeAI's separation of entity, endpoint, workflow, integration, etc.) make IVP the path of least resistance.

This review evaluates whether CodeAI succeeds in this linguistic support for IVP. If it does, the language not only benefits LLM code generation (through semantic clarity) but also human maintainability (through enforced concern separation).

1.3 Review Methodology

This review analyzes CodeAI's syntax and semantics through:

1. Syntactic Domain Analysis: Identifying top-level language constructs
2. Concern Mapping: Mapping change drivers to language constructs
3. Variation Scenario Testing: Evaluating independence through hypothetical change scenarios
4. Comparison Analysis: Contrasting with traditional mixed-concern frameworks

Source Material: Official examples from the CodeAI repository (examples/ directory, v1.0).

---

2. Architectural Analysis

2.1 Identified Syntactic Domains

CodeAI provides seven top-level declarative constructs, each targeting a distinct architectural concern:

Construct	Syntax	Purpose	Lines of Code*
Configuration	config { }	Infrastructure settings	14-46
Entity	entity Name { }	PostgreSQL data models	41-193
Collection	database mongodb { collection { } }	MongoDB document schemas	19-242
Endpoint	endpoint METHOD /path { }	RESTful API definitions	200-617
Event	event Name { }	Event-driven messaging	623-711
Integration	integration Name { }	External service clients	422-555
Workflow	workflow Name { }	Multi-step business processes	560-782
Job	job Name { }	Scheduled background tasks	197-653

*Line ranges from example files: blog-api.cai, ecommerce.cai, mongodb-collections.cai, scheduled-jobs.cai

2.2 Concern-to-Construct Mapping

Each syntactic domain addresses a specific change driver:

2.2.1 Infrastructure Configuration Concern

Change Driver: "How the application runtime is configured"

Variation Point: config { } block

config {
    name: "blog-api"
    version: "1.0.0"

    database: postgres {
        pool_size: 20
        timeout: 30s
    }

    cache: redis {
        ttl: 5m
        prefix: "blog:"
    }

    auth: jwt {
        issuer: env(JWT_ISSUER)
        secret: env(JWT_SECRET)
        expiry: 24h
    }
}

IVP Assessment: ✅ Compliant

• Database configuration varies independently of entity definitions
• Cache settings can change without modifying endpoints
• Authentication parameters isolated from business logic

2.2.2 Data Schema Concern (Relational)

Change Driver: "What data structures the application persists"

Variation Point: entity { } blocks

entity Post {
    description: "A blog post with content and metadata"

    id: uuid, primary, auto

    // Content
    title: string, required, searchable
    slug: string, required, unique
    content: text, required, searchable

    // Relationships
    author_id: ref(User), required
    category_id: ref(Category), optional

    // Tags (stored as JSON array)
    tags: list(string), optional

    // Publishing
    status: enum(draft, pending_review, published, archived), default(draft)
    published_at: timestamp, optional

    created_at: timestamp, auto
    updated_at: timestamp, auto_update

    index: [author_id, status]
    index: [slug]
}

IVP Assessment: ✅ Compliant

• Schema evolution localized to entity definitions
• Adding fields doesn't require endpoint modifications
• Index changes independent of business logic

2.2.3 Data Schema Concern (Document)

Change Driver: "How document-oriented data is structured"

Variation Point: database mongodb { collection { } } blocks

database mongodb {
    collection Product {
        description: "E-commerce products with variants"

        _id: objectid, primary, auto
        sku: string, required, unique
        name: string, required

        // Embedded document for attributes
        attributes: embedded {
            color: string, optional
            size: string, optional
            dimensions: embedded {
                length: double, optional
                width: double, optional
                height: double, optional
            }
        }

        categories: array(string), optional

        indexes {
            index: [sku] unique
            index: [name, description] text
        }
    }
}

IVP Assessment: ✅ Compliant

• MongoDB schemas separated from relational schemas
• Embedded document structures vary independently
• Geospatial and text indexes localized to collections

2.2.4 API Surface Concern

Change Driver: "What HTTP endpoints are exposed and how they behave"

Variation Point: endpoint { } blocks

// Create post (author/editor/admin)
endpoint POST /posts {
    description: "Create a new post"
    auth: required
    roles: [author, editor, admin]

    body {
        title: string, required
        slug: string, required
        content: text, required
        category_id: uuid, optional
        tags: list(string), optional
        status: string, optional
    }

    returns: Post
    on_success: emit(PostCreated)
}

IVP Assessment: ✅ Compliant

• Endpoint definitions independent of entity schemas
• Authentication requirements vary per-endpoint
• Request/response contracts localized
• Role-based access control declarative and isolated

2.2.5 Event-Driven Messaging Concern

Change Driver: "What events are published and their payloads"

Variation Point: event { } blocks

event PostPublished {
    description: "Post published"
    payload {
        post_id: uuid
        title: string
        slug: string
        published_at: timestamp
    }
    publish_to: [webhook("post-updates"), kafka("posts")]
}

IVP Assessment: ✅ Compliant

• Event contracts vary independently of endpoints that emit them
• Payload structure changes don't affect entity definitions
• Publishing destinations (Kafka, webhooks) configurable per-event

2.2.6 External Integration Concern

Change Driver: "How external services are consumed"

Variation Point: integration { } blocks

integration PaymentGateway {
    description: "Stripe payment processing"
    type: rest
    base_url: env(STRIPE_API_URL)

    auth: bearer(env(STRIPE_SECRET_KEY))

    timeout: 30s
    retry: 3 times with exponential_backoff
    circuit_breaker: {
        threshold: 5 failures in 1m
        reset_after: 30s
    }

    operation create_payment_intent {
        method: POST
        path: "/payment_intents"
        body: {
            amount: integer, required
            currency: string, default("usd")
        }
        returns: {
            id: string
            status: string
            client_secret: string
        }
    }
}

IVP Assessment: ✅ Compliant

• Integration definitions isolated from workflows that consume them
• Retry and circuit breaker policies vary independently
• Switching providers (Stripe → PayPal) requires only integration block changes
• Fault tolerance strategies localized

2.2.7 Business Process Concern

Change Driver: "How multi-step business workflows execute"

Variation Point: workflow { } blocks

workflow OrderProcessing {
    description: "Process an order from placement to fulfillment"
    trigger: OrderPlaced

    steps {
        // Step 1: Validate order
        validate_order {
            for_each: trigger.order.items
            check: item.product.available_quantity >= item.quantity
            on_fail: cancel_order("Insufficient inventory")
        }

        // Step 2: Reserve inventory (with compensation)
        reserve_inventory {
            for_each: trigger.order.items
            action: reserve_product_inventory(item.product_id, item.quantity)
            timeout: 30s
            retry: 3 times with exponential_backoff
            on_fail: rollback
        }

        // Step 3: Process payment (with compensation)
        process_payment {
            call: PaymentGateway.create_payment_intent {
                amount: trigger.order.total * 100
            }
            timeout: 30s
            on_fail: rollback
        }

        confirm_order {
            action: update(trigger.order.status = "confirmed")
        }
    }

    on_complete: emit(OrderConfirmed)
    on_fail: emit(OrderFailed)
}

IVP Assessment: ✅ Compliant

• Workflow orchestration logic separated from entity definitions
• Saga pattern with compensation localized to workflow
• Adding/removing steps doesn't affect endpoints or integrations
• Error handling and retry strategies per-step

2.2.8 Scheduled Task Concern

Change Driver: "When and how background jobs execute"

Variation Point: job { } blocks

job DailySalesReport {
    description: "Generate daily sales report"
    schedule: "0 6 * * *"                 // Every day at 6:00 AM
    timezone: "America/New_York"

    queue: default
    timeout: 30m
    retry: 3 times

    steps {
        fetch_sales {
            query: select Order
                where status = "completed"
                and created_at >= yesterday_start()
            as: orders
        }

        generate_report {
            template: "daily_sales_report"
            data: { orders: orders }
            format: pdf
            as: report_file
        }

        distribute {
            send: email(config.reports.recipients) {
                template: "daily_report_email"
                attachment: report_file
            }
        }
    }

    on_complete: emit(ReportGenerated)
}

IVP Assessment: ✅ Compliant

• Job scheduling (cron expressions) varies independently of business logic
• Changing report frequency doesn't affect entity schemas
• Queue priorities and timeouts localized to job definitions
• Retry strategies per-job

---

3. Variation Scenario Testing

To validate IVP compliance, we test hypothetical change scenarios across each concern.

3.1 Scenario: Change Payment Provider

Change Driver: External payment integration (Stripe → PayPal)

Required Changes:

• Modify integration PaymentGateway block only
• Update operation definitions for PayPal API
• Change authentication from bearer to api_key

Unaffected Components:

• ✅ Entity definitions (Order, Payment remain unchanged)
• ✅ Endpoint definitions (checkout endpoint unchanged)
• ✅ Workflow logic (OrderProcessing calls remain syntactically identical)
• ✅ Event definitions (OrderConfirmed payload unchanged)

IVP Verdict: ✅ Independent variation achieved. The "payment provider integration" concern varies in exactly one place.

3.2 Scenario: Add Gift Message to Orders

Change Driver: Order entity schema evolution

Required Changes:

• Add gift_message: string, optional to entity Order

Unaffected Components:

• ✅ Configuration (database settings unchanged)
• ✅ Endpoints (automatically handle new optional field)
• ✅ Workflows (OrderProcessing logic unchanged)
• ✅ Integrations (payment gateway unaffected)

IVP Verdict: ✅ Independent variation achieved. The "order data structure" concern varies in exactly one place.

3.3 Scenario: Change Report Schedule

Change Driver: Scheduled job timing (6am → 7am)

Required Changes:

• Modify schedule: "0 6 * * *" to schedule: "0 7 * * *" in job DailySalesReport

Unaffected Components:

• ✅ Entity definitions (Report entity unchanged)
• ✅ Endpoints (report listing unchanged)
• ✅ Workflows (unrelated to scheduling)
• ✅ Job business logic (report generation steps unchanged)

IVP Verdict: ✅ Independent variation achieved. The "when jobs run" concern varies in exactly one place.

3.4 Scenario: Add Fraud Detection to Order Processing

Change Driver: Business workflow logic enhancement

Required Changes:

• Add new step to workflow OrderProcessing:

  check_fraud {
      call: FraudDetectionService.analyze {
          order_id: trigger.order.id
          amount: trigger.order.total
      }
      on_fail: cancel_order("Fraud detected")
  }

Unaffected Components:

• ✅ Entity definitions (Order entity unchanged)
• ✅ Endpoints (checkout endpoint unchanged)
• ✅ Integrations (PaymentGateway unchanged, new FraudDetectionService separate)
• ✅ Events (OrderPlaced unchanged, workflow internal)

IVP Verdict: ✅ Independent variation achieved. The "order processing logic" concern varies in exactly one place.

3.5 Scenario: Change Authentication from JWT to OAuth2

Change Driver: Authentication mechanism

Required Changes:

• Modify config { auth: { } } block
• Update from jwt to oauth2 configuration

Unaffected Components:

• ✅ Entity definitions (unchanged)
• ✅ Endpoint definitions (auth policies declarative, runtime handles)
• ✅ Workflows (authentication orthogonal)
• ⚠️ Runtime implementation must support OAuth2 (implementation concern, not DSL concern)

IVP Verdict: ✅ Mostly independent variation. Configuration change localized; endpoint auth: required declarations remain valid.

---

4. Comparison: Mixed-Concern Frameworks

To contextualize CodeAI's IVP compliance, compare with traditional frameworks that entangle concerns.

4.1 Rails Model (Mixed Concerns)

class Order < ApplicationRecord
  # CONCERN 1: Schema/Relationships
  belongs_to :customer
  has_many :order_items

  # CONCERN 2: Validation
  validates :total, presence: true, numericality: { greater_than: 0 }

  # CONCERN 3: Business Logic
  def process!
    reserve_inventory
    charge_payment
    send_confirmation
    self.status = 'confirmed'
    save!
  end

  # CONCERN 4: Queries
  scope :pending, -> { where(status: 'pending') }
  scope :completed, -> { where(status: 'completed') }

  # CONCERN 5: Callbacks
  after_create :send_order_placed_event
  before_destroy :refund_payment
end

IVP Violations:

• ❌ Schema and business logic in same file
• ❌ Changing workflow requires touching model
• ❌ Query scopes mixed with validation rules
• ❌ Callbacks entangle lifecycle with business events

4.2 CodeAI Equivalent (Separated Concerns)

// CONCERN 1: Schema (entity Order { })
entity Order {
    id: uuid, primary, auto
    customer_id: ref(Customer), required
    total: decimal(10,2), required
    status: enum(pending, confirmed, ...), default(pending)
}

// CONCERN 2: Validation (embedded in endpoint)
endpoint POST /orders {
    body {
        total: decimal, required, min(0.01)
    }
}

// CONCERN 3: Business Logic (workflow OrderProcessing { })
workflow OrderProcessing {
    steps {
        reserve_inventory { ... }
        charge_payment { ... }
        send_confirmation { ... }
        confirm_order { ... }
    }
}

// CONCERN 4: Queries (used in endpoints/workflows where needed)
endpoint GET /orders {
    query {
        status: string, optional
    }
}

// CONCERN 5: Events (event OrderPlaced { })
event OrderPlaced {
    payload { order_id: uuid, ... }
}

IVP Advantages:

• ✅ Changing workflow doesn't touch entity
• ✅ Schema evolution independent of validation
• ✅ Event contracts separated from business logic
• ✅ Each concern has single, clear variation point

---

5. Language Design Patterns Supporting IVP

5.1 Mandatory Structural Boundaries

CodeAI enforces separation through syntax:

// ✅ Valid: Endpoint references entity
endpoint GET /users/{id} {
    returns: User
}

// ❌ Invalid: Cannot define entity inside endpoint
endpoint GET /users/{id} {
    entity User { ... }  // Syntax error
}

// ❌ Invalid: Cannot embed workflow in integration
integration API {
    workflow Process { ... }  // Syntax error
}

IVP Benefit: Language prevents accidental concern entanglement at parse time.

5.2 Declarative Reference Semantics

Concerns reference each other declaratively without embedding:

// Endpoint references entity (doesn't embed it)
endpoint POST /posts {
    returns: Post
}

// Workflow calls integration (doesn't define it)
workflow OrderProcessing {
    process_payment {
        call: PaymentGateway.create_payment_intent { ... }
    }
}

// Event references entity (doesn't own it)
event PostCreated {
    payload {
        post_id: uuid  // References Post.id
    }
}

IVP Benefit: References create coupling at usage sites, but definitions remain independently variable.

5.3 Single Responsibility per Block

Each top-level block has exactly one responsibility:

Block Type	Responsibility	Not Responsible For
entity	Schema definition	API exposure, business logic, scheduling
endpoint	API contract	Data storage, workflow orchestration, events
workflow	Process orchestration	Schema definition, API routing, scheduling
job	Temporal scheduling	Schema, endpoints, immediate workflows
integration	External service client	Internal entities, workflows, events
event	Message contract	Publishers, subscribers, data storage
config	Infrastructure settings	Business logic, schema, API surface

IVP Benefit: Each block varies for exactly one reason.

5.4 Compositional Rather Than Hierarchical

Blocks compose through references, not containment:

// Composition: workflow uses integration + entity + event
workflow OrderProcessing {
    trigger: OrderPlaced             // Composes with event

    process_payment {
        call: PaymentGateway.create  // Composes with integration
    }

    confirm_order {
        action: update(order.status)  // Composes with entity
    }
}

// Each composed concern varies independently

IVP Benefit: Composition maintains independence; hierarchy would create cascading changes.

---

6. Potential IVP Concerns

6.1 Cross-Cutting Retry Logic

Observation: Retry strategies appear in multiple constructs:

// In integration
integration API {
    retry: 3 times with exponential_backoff
}

// In workflow step
workflow Process {
    steps {
        call_api {
            retry: 5 times
        }
    }
}

// In job
job Task {
    retry: 2 times
}

Analysis: This is not an IVP violation. Each retry concern is distinct:

• Integration retries = "How external service calls recover from transient failures"
• Workflow step retries = "How individual workflow steps recover"
• Job retries = "How entire job executions recover"

These are different change drivers at different architectural layers.

Verdict: ✅ Acceptable repetition of a pattern, not repetition of a concern.

6.2 Validation in Multiple Places

Observation: Validation logic appears in:

• Entity field constraints: title: string, required
• Endpoint body validation: body { title: string, required }

Analysis: These are different concerns:

• Entity constraints = "What the database schema enforces"
• Endpoint validation = "What the API contract requires"

Valid API input might still violate database constraints (e.g., optional in API, required in DB for existing records).

Verdict: ✅ Not an IVP violation; distinct validation layers with different purposes.

6.3 Data Structure Duplication

Observation: Event payloads sometimes mirror entity fields:

entity Post {
    id: uuid
    title: string
    slug: string
}

event PostPublished {
    payload {
        post_id: uuid
        title: string
        slug: string
    }
}

Analysis: These are different concerns:

• Entity = "Persistent storage structure"
• Event = "Message contract for external consumers"

They may evolve independently (e.g., entity adds internal fields not exposed in events).

Verdict: ✅ Not an IVP violation; events intentionally denormalize for stable contracts.

---

7. Conclusion

7.1 Overall IVP Compliance Rating

Grade: A (Excellent IVP Compliance)

CodeAI demonstrates strong adherence to the Independent Variation Principle across all evaluated dimensions:

Criterion	Rating	Evidence
Concern Identification	✅ Excellent	Seven distinct syntactic domains clearly identified
Localization	✅ Excellent	Each concern has single, well-defined variation point
Independence	✅ Excellent	Variation scenarios confirm independent mutability
Non-Repetition	✅ Excellent	Concerns expressed exactly once; apparent repetition is pattern reuse
Enforcement	✅ Excellent	Language syntax prevents concern entanglement

7.2 Key Strengths

1. Syntactic Enforcement: Language design prevents accidental concern mixing through parse-time validation
2. Declarative Composition: Blocks reference rather than embed each other, maintaining independence
3. Domain Alignment: Constructs map naturally to architectural concerns in backend systems
4. Scalability: Seven distinct variation points allow systems to grow along multiple independent axes

7.3 Architectural Implications

For Maintainability:

• Changes localize predictably to single files/blocks
• Reduced cognitive load: developers work within single concern at a time
• Lower regression risk: isolated changes reduce cascading failures

For Team Scalability:

• Different developers can own different concerns (schema team, API team, workflow team)
• Parallel development enabled by independence
• Clear boundaries reduce merge conflicts

For Evolution:

• Concerns can evolve at different rates without coordination
• Technology substitution simplified (swap Redis for Memcached in config only)
• Feature additions don't require refactoring existing concerns

7.4 Comparison to Original Claim

Original Claim (Barış Gömeç): "Simpler declarative syntax maps more directly to semantic meaning — making it easier for LLMs to generate accurate, production-ready code."

IVP Finding: The same properties that benefit LLMs (clear semantic boundaries, declarative structure, single-purpose constructs) also benefit human maintainability through IVP compliance.

Synthesis: CodeAI is optimized for both:

1. LLM code generation (clear semantic mapping)
2. Human code maintenance (independent variation of concerns)

These are not competing goals—they emerge from the same underlying principle: semantic clarity through concern separation.

7.5 Recommendations

For Language Evolution:

1. Maintain syntactic boundaries: Resist temptation to add "convenience features" that mix concerns
2. Document concern mapping: Explicitly state which construct handles which change driver
3. Add linting: Enforce IVP at tooling level (e.g., warn if workflow embeds schema logic)

For Users:

1. Respect boundaries: Don't work around constructs; use them as designed
2. One concern per file: Consider organizing large systems with one entity/endpoint/workflow per file
3. Reference, don't duplicate: Use composition over copy-paste

For Researchers:

1. Empirical study: Measure maintenance velocity in CodeAI vs. traditional frameworks
2. Cognitive load: Study developer comprehension with separated vs. entangled concerns
3. LLM performance: Compare accuracy of LLM-generated CodeAI vs. traditional code

---

8. References

8.1 Primary Sources

• CodeAI GitHub Repository: https://github.com/bargom/codeai
  • examples/02-blog-api/blog-api.cai
  • examples/03-ecommerce/ecommerce.cai
  • examples/05-scheduled-jobs/scheduled-jobs.cai
  • examples/06-mongodb-collections/mongodb-collections.cai
• Original LinkedIn Post: Barış Gömeç, "I asked AI to design a programming language..."
• CodeAI Website: https://cai-lang.dev

8.2 IVP Background

• Loth, Y. (2025). "The Independent Variation Principle: A Unifying Framework for Software Design." Zenodo. https://doi.org/10.5281/zenodo.17677315
  • Formal definition of IVP: "Separate elements with different change driver assignments into distinct units; unify elements with the same change driver assignment within a single unit."
  • Provides mathematical formalization of change drivers, change driver assignments, and architectural quality metrics
• Dijkstra, E. W. (1982). "On the role of scientific thought." Selected Writings on Computing: A Personal Perspective.
• Martin, R. C. (2003). Agile Software Development: Principles, Patterns, and Practices (Single Responsibility Principle)
• Parnas, D. L. (1972). "On the Criteria To Be Used in Decomposing Systems into Modules." Communications of the ACM.

8.3 Related Principles

• SOLID Principles: SRP, OCP, LSP, ISP, DIP (Robert C. Martin)
• Separation of Concerns (SoC): Dijkstra, Parnas
• Don't Repeat Yourself (DRY): Hunt & Thomas, The Pragmatic Programmer
• Single Source of Truth (SSOT): Database design, data management

---

9. Appendix: Formal IVP Evaluation Matrix

Concern	Construct	Change Examples	Isolation Score	Independence Score	Overall
Infrastructure Config	config { }	DB pool size, cache TTL, JWT expiry	5/5	5/5	✅ Excellent
Relational Schema	entity { }	Add fields, change indexes, alter types	5/5	5/5	✅ Excellent
Document Schema	collection { }	Embedded docs, arrays, geospatial	5/5	5/5	✅ Excellent
API Surface	endpoint { }	Add parameters, change auth, modify responses	5/5	4/5	✅ Very Good*
Event Contracts	event { }	Modify payloads, change publishers	5/5	5/5	✅ Excellent
External Integration	integration { }	Change providers, update retries, modify circuit breakers	5/5	4/5	✅ Very Good**
Business Workflows	workflow { }	Add steps, modify saga logic, change timeouts	5/5	4/5	✅ Very Good***
Scheduled Jobs	job { }	Change cron schedule, update queue, modify retries	5/5	5/5	✅ Excellent

Legend:

• Isolation Score: How well the concern is localized (5 = single file/block)
• Independence Score: How independently it can vary (5 = zero coupling to other concerns)

Notes:

• * Endpoints reference entities in returns: clauses (unavoidable semantic coupling)
• ** Integrations are called from workflows (usage coupling, not definition coupling)
• *** Workflows compose entities, integrations, events (orchestration requires references)

---