Chronos — Language Reference

Chronos Documentation: ← Introduction & Getting Started | Language Reference | Examples & Artifacts → | CLI Reference →

Language Fundamentals

File Structure

All Chronos source files use the .chronos extension. A project is a collection of .chronos files organized into namespaces.

project-root/
├── chronos-build.json      # Build configuration
├── requirements/
│   ├── common/
│   │   ├── actors.chronos
│   │   ├── entities.chronos
│   │   └── policies.chronos
│   ├── checkout/
│   │   ├── guest-checkout.chronos
│   │   └── returning-customer.chronos
│   └── onboarding/
│       └── user-registration.chronos
└── artifacts/              # Generated output

Namespaces

Every .chronos file begins with a namespace declaration:

namespace com.genairus.commerce.checkout

Rules:

• One namespace declaration per file (must be first non-comment statement)
• Use reverse domain notation (e.g., com.company.domain.subdomain)
• Segments must be lowercase alphanumeric, separated by dots

Imports

Import shapes from other namespaces with use statements:

namespace com.genairus.commerce.checkout

use com.genairus.common.actors#Customer
use com.genairus.common.entities#Order
use com.genairus.common.entities#Money

Syntax: use <namespace>#<ShapeName>

Rules:

• use statements must appear after namespace and before shape definitions
• Circular imports are a validation error

Comments

Chronos supports two comment styles:

// Single-line comment. Ignored by the generator.

/// Documentation comment.
/// Included in generated work item descriptions, PRDs, and API docs.
/// Supports inline Markdown formatting.

Primitive Types

Shape Definitions

Shapes are the building blocks of Chronos. They represent concepts in your product domain.

Entities

Entities represent the data model of your product—business objects with identity.

@pii
@sensitivity("high")
entity Order {
    @required
    id: String

    @required
    items: List<OrderItem>

    total: Money
    status: OrderStatus
}

Rules:

• Entity names must be PascalCase
• Fields are name: Type pairs, separated by commas
• Fields without @required are optional by default
• Can reference other entities, lists, enums, and shapes

Shapes (Value Objects)

Shapes are lightweight data containers for value objects or sub-components:

shape OrderItem {
    @required
    sku: String

    @required
    quantity: Integer

    unitPrice: Money
}

shape Money {
    @required
    amount: Float

    @required
    currency: Currency
}

Entities vs. Shapes:

• Entities: Top-level business objects with identity (have an id field)
• Shapes: Value objects describing what something is, not which one it is

Collections

Lists (ordered collections):

// Generic syntax (recommended)
items: List<OrderItem>

// Named list shape (for complex validation)
list OrderItemList {
    member: OrderItem
}

Maps (key-value collections):

// Generic syntax
metadata: Map<String, String>

// Named map shape
map MetadataMap {
    key: String
    value: String
}

Enums

Enums define a fixed set of named values:

enum OrderStatus {
    PENDING
    PAID
    SHIPPED
    CANCELLED
}

Or with explicit ordinal values:

enum OrderStatus {
    PENDING = 1
    PAID = 2
    SHIPPED = 3
    CANCELLED = 4
}

Rules:

• Enum members must be UPPER_SNAKE_CASE
• Ordinal values (if used) must be unique positive integers
• Enums are closed—they can't be extended outside their definition

Actors

Actors define who or what interacts with the system:

@description("A registered user who has authenticated via SSO or credentials")
actor AuthenticatedUser

@description("An automated service that processes payments via Stripe")
actor PaymentGateway

@description("A first-time visitor with no existing account")
actor GuestUser

Rules:

• Actor names must be PascalCase
• Actors should include a @description trait
• Actors referenced in journeys must be defined or imported

Policies

Policies are global rules representing business constraints or regulatory requirements:

@compliance("GDPR")
policy DataRetention {
    description: "Personal data must be purged after 7 years of account inactivity"
}

@compliance("PCI-DSS")
policy CardDataHandling {
    description: "Raw card numbers must never be stored. Only tokenized references are permitted"
}

@compliance("HIPAA")
policy ProtectedHealthInfo {
    description: "All PHI must be encrypted at rest and in transit. Access requires role-based authorization"
}

Journeys: The Behavioral Core

A journey is the central construct in Chronos. It represents a cohesive unit of value—what you might call a "feature," "use case," or "user story."

Journey Structure

A journey is composed of:

Complete Journey Example

@kpi(metric: "CheckoutConversion", target: ">75%")
@owner("product-checkout-team")
journey GuestCheckout {
    actor: Customer

    preconditions: [
        "Cart is not empty",
        "Actor is not logged in"
    ]

    steps: [
        step ProvideShipping {
            action: "Submits shipping address form"
            expectation: "System validates address and calculates available shipping methods and taxes"
            outcome: TransitionTo(ShippingMethodsDisplayed)
        },

        step ChoosePayment {
            action: "Selects Credit Card and enters payment details"
            expectation: "System validates card format via Luhn check and calculates final total"
            telemetry: [PaymentMethodSelectedEvent]
            risk: "High latency from third-party address validation service (avg 1.2s)"
        },

        step PlaceOrder {
            @slo(latency: "2s", p99: true)
            action: "Clicks 'Place Order'"
            expectation: "Order is created with status PAID and confirmation email is queued"
            outcome: TransitionTo(OrderConfirmed)
            telemetry: [OrderPlacedEvent, PaymentProcessedEvent]
        }
    ]

    outcomes: {
        success: "Order record exists with status PAID and confirmation email has been dispatched",
        failure: "Cart remains intact, user is presented with an actionable error message"
    }
}

Steps

A step is a single interaction between the actor and the system.

Rules:

• Steps are ordered—the generator processes them sequentially
• Every action must be attributable to the journey's declared actor
• Expectations must not contain fuzzy language—words like "fast," "easy," "intuitive" are validation warnings

Outcomes & State Transitions

Outcomes define the terminal states of a journey:

outcomes: {
    success: "Profile record exists with status VERIFIED and welcome email sent",
    failure: "User is redirected to error page with retry option"
}

The TransitionTo(StateName) function creates a named state transition:

outcome: TransitionTo(ShippingMethodsDisplayed)

Rules:

• Every journey must define a success outcome
• Every journey must reach a terminal state—no dead-end paths
• State names in TransitionTo() must be unique within the journey scope

The Trait System

Traits are the adjectives of Chronos. They attach metadata, constraints, and behavioral annotations to shapes. Traits are applied using the @ symbol.

Trait Syntax

Traits can be applied in three forms:

// 1. Bare trait (no arguments)
@pii
entity CustomerProfile { ... }

// 2. Single-argument trait
@description("A verified customer account")
actor VerifiedUser

// 3. Multi-argument trait
@slo(latency: "500ms", p99: true)
step LoadProfile { ... }

Common Built-in Traits

Journey-Level Traits

Entity-Level Traits

Step-Level Traits

Field-Level Traits

Custom Traits

You can define custom traits for your organization:

@trait
structure teamOwned {
    team: String
    slack: String
}

@teamOwned(team: "payments", slack: "#payments-squad")
journey ProcessRefund { ... }

Variants & Branching

Variants handle alternative flows and error conditions.

Basic Variant

journey GuestCheckout {
    actor: Customer

    steps: [
        step ProvideShipping { ... },
        step ChoosePayment { ... }
    ]

    variants: {
        InvalidAddress: {
            trigger: "Address validation fails"
            steps: [
                step ShowAddressError {
                    expectation: "System displays address correction suggestions"
                    outcome: TransitionTo(AddressFormRedisplayed)
                }
            ]
            outcome: ReturnToStep(ProvideShipping)
        }
    }

    outcomes: {
        success: "Order created with status PAID",
        failure: "Cart remains intact with error message"
    }
}

Multiple Variants

variants: {
    PaymentDeclined: {
        trigger: "Payment gateway returns declined status"
        steps: [
            step NotifyDecline {
                expectation: "System displays payment declined message with retry option"
            }
        ]
        outcome: ReturnToStep(ChoosePayment)
    },

    InventoryUnavailable: {
        trigger: "One or more items out of stock"
        steps: [
            step ShowInventoryError {
                expectation: "System displays out-of-stock items and suggests alternatives"
            }
        ]
        outcome: TransitionTo(CartReviewRequired)
    }
}

Appendix

Built-in Trait Reference

Journey Traits

Entity/Shape Traits

Step Traits

Field Traits

Validation Rules Reference

Chronos Documentation: ← Introduction & Getting Started | Language Reference | Examples & Artifacts → | CLI Reference →