DCL Language Reference

This reference describes DCL by language construct. It is based on the repository's primitive contracts, surface syntax direction, compiler duties, context semantics, policy semantics, and lifecycle documents, adjusted to the current compiler-supported language shape.

Current language: DCL v1.1. Status: Stable language core. Compiler: 1.1.0.

For local AI-assisted validation and analysis, see the Tooling page and MCP setup guide.

Construct Index

Program

A DCL program is a set of source files compiled together into a validated semantic model. Files are authoring units; compiler meaning must not depend on file order or declaration order.

The compiler is the source of truth for example validity. It rejects errors such as undefined symbols, missing capability intent, missing outcomes, invalid policy concerns, and invalid lifecycle references.

Context

A context is a semantic ownership boundary. It is not a file, folder, package, deployment unit, or runtime module. A context groups declarations into an area of architectural responsibility.

Ownership

Every declaration belongs to exactly one context: capability, actor, event, effect, policy, and shape declarations are all owned by their containing context.

Dependencies

Dependencies are explicit. A context that uses declarations from another context must declare depends on ContextName. Visibility is not transitive: if A depends on B, and B depends on C, A does not automatically see C.

Cycles

Circular dependencies are invalid. Resolve cycles by extracting common declarations into a shared context, by using events between contexts, or by moving ownership to a higher-level capability.

language dcl 1.0

context Shared {
  actor Customer is human

  shape SharedOrderInput {
    orderId: Uuid required
    customerId: Uuid required
  }

  event SharedOrderSubmitted is {
    orderId: Uuid required
  }
}

language dcl 1.0

context Sales {
  depends on Shared

  effect PersistSalesOrder is persistence

  capability AcceptSalesOrder {
    intent SharedOrderInput from Customer

    outcomes {
      SalesOrderAccepted
      SalesOrderDeferred
    }

    effect PersistSalesOrder

    observe {
      event SharedOrderSubmitted count as shared_orders_submitted
      outcome SalesOrderAccepted count as sales_orders_accepted
    }

    when {
      PersistSalesOrder unresolved then SalesOrderDeferred
      otherwise then SalesOrderAccepted
    }
  }
}

Type system and shapes

Since DCL 1.1: Integer, numeric constraints, measures, measured numerics, enum shapes, and typed enum cases.

DCL types encode domain distinctions, not merely storage representation. A shape is a first-class named domain type: record shapes compose fields and other types, while enum shapes define a closed set of alternatives.

Types describe data and domain meaning. They do not add methods, inheritance, or runtime behaviour to a capability.

Jump to built-in types, record shapes, numeric constraints, enum shapes, Result/Either-style types, measures, or the complete domain example.

Built-in types

The compiler supports Text, Boolean, Integer, Number, Date, and DateTime. It also supports the convenience value types Uuid, Email, and Money.

language dcl 1.1

shape Product {
  stock: Integer
  price: Number
}

Integer is a signed integral numeric type and is distinct from Number. Use Integer for whole-number concepts such as counts; use Number where fractional values are meaningful.

Record shapes

A record shape declares a reusable named domain type. Its fields may use a built-in type, another record or enum shape, a List<T>, or a measured numeric type. required marks a structurally mandatory field.

shape Address {
  line1: Text required
  city: Text required
}

shape Customer {
  name: Text required
  address: Address required
}

Here Customer composes Address; neither shape is limited to use as a capability request or event payload.

Numeric constraints

Since DCL 1.1.

Integer and Number fields, including measured forms, support min, max, and default.

shape RetryConfiguration {
  attempts: Integer min 0 max 10 default 3
  delaySeconds: Number min 0 max 60 default 1.5
}

These are structural/type constraints, not capability rules. The compiler checks that numeric literals are valid, min is not greater than max, defaults fall within the declared range, and Integer constraints do not contain fractional values.

shape RetryConfiguration {
  attempts: Integer min 1 max 5 default 10
}

This definition is invalid: the compiler reports DCL_SEM_NUMERIC_DEFAULT_OUT_OF_RANGE because 10 is above the maximum of 5.

Enum shapes

Since DCL 1.1.

An enum shape is a closed set of named alternatives. An alternative carries either no value or one value of another DCL type. The is keyword associates a value-carrying alternative with its type.

shape Currency enum {
  GBP
  USD
  EUR
}

shape HexColour {
  value: Text required
}

shape Colour enum {
  Red
  Green
  Blue
  Hex is HexColour
}

Alternatives may carry record shapes, built-ins, enum shapes, collections, or measured numerics. They always use is; call-like forms such as Card(CardDetails) are not DCL syntax.

shape CardDetails {
  token: Text required
}

shape BankAccount {
  accountNumber: Text required
}

shape PaymentMethod enum {
  Cash
  Card is CardDetails
  BankTransfer is BankAccount
}

shape SearchValue enum {
  TextValue is Text
  NumericValue is Integer
}

Result/Either-style domain types

Since DCL 1.1. These are ordinary typed enum cases, not a special built-in Result type.

shape Failure {
  name: Text
  reason: Text required
  code: Number
}

shape Result enum {
  Success
  Failed is List<Failure>
}

Failed carries a List<Failure>. Result/Either-style domain models therefore use ordinary enum shapes; Result is not a special built-in type.

Measures and measured numeric types

Since DCL 1.1.

A measure gives a numeric value a lightweight unit of domain meaning.

measure Quantity
measure Weight
measure Days

shape OrderLine {
  quantity: Integer<Quantity> min 1 required
  unitWeight: Number<Weight> required
}

shape RetentionPolicy {
  retention: Integer<Days> min 1 required
}

Integer<Quantity>, Integer<Days>, and unmeasured Integer are semantically distinct types even though they share a numeric representation. Measures are intentionally lightweight: the compiler does not provide automatic conversion, dimensional algebra, derived units, or an SI library.

Complex and nested domain types

Record shapes, enum shapes, collections, measured numerics, and constraints compose into larger business models. The following compiler-validated source includes ordering, delivery, payment, search, and failure types.

language dcl 1.1

measure Items
measure Weight
measure Days

shape Product {
  stock: Integer
  price: Number
}

shape RetryConfiguration {
  attempts: Integer min 0 max 10 default 3
  delaySeconds: Number min 0 max 60 default 1.5
}

shape Address {
  line1: Text required
  city: Text required
  postcode: Text required
}

shape Customer {
  name: Text required
  address: Address required
}

shape Currency enum {
  GBP
  USD
  EUR
}

shape HexColour {
  value: Text required
}

shape Colour enum {
  Red
  Green
  Blue
  Hex is HexColour
}

shape CardDetails {
  token: Text required
}

shape BankAccount {
  accountNumber: Text required
}

shape PaymentMethod enum {
  Cash
  Card is CardDetails
  BankTransfer is BankAccount
}

shape SearchValue enum {
  TextValue is Text
  NumericValue is Integer
}

shape Failure {
  name: Text
  reason: Text required
  code: Number
}

shape Result enum {
  Success
  Failed is List<Failure>
}

shape DeliveryMethod enum {
  Collection
  HomeDelivery is Address
}

shape OrderLine {
  productId: Text required
  quantity: Integer<Items> min 1 required
  unitWeight: Number<Weight> min 0 required
}

shape Order {
  lines: List<OrderLine> required
  payment: PaymentMethod required
  delivery: DeliveryMethod required
}

shape RetentionPolicy {
  retention: Integer<Days> min 1 required
}

Enum shapes remain data/domain types. For example, shape ValidationResult enum { ... } describes a reusable value. A capability outcomes { ... } block describes behaviour and causation. Similar payload types may be reused, but the two constructs have different language semantics.

Actor

An actor represents an initiating or participating party. DCL v1.0 accepts only the actor types listed below.

Other actor type names are rejected by the DCL v1.0 compiler. Use system for software/system participants, and model approval or decision responsibility through rules, policies, and actor roles.

Event

An event is a named signal. Events may have structured payloads. Capability event declarations state which events the capability is an emission source for; they do not prescribe broker, topic, transport, or delivery semantics.

Lifecycle waits and transitions can reference events. In a local lifecycle, omitted event source means the owning capability when ownership is clear. In a supervising lifecycle, the source capability must be explicit.

Effect

An effect declares an externally meaningful action caused by a capability. Effects describe semantic change, not infrastructure mechanics.

Effects may be used singly or in an ordered effects block. after expresses explicit ordering.

Policy

Policies express portable execution qualities. Authors declare policies and attach them to semantic boundaries. The compiler derives effective policy envelopes; authors do not write those envelopes directly.

Families

A policy block may contain one family block or several grouped family blocks. Concerns belong to the family block that contains them. The older family name line form is accepted for compatibility, but the grouped block form is preferred for DCL v1.0 examples.

policy SupportExecution {
  reliability {
    retry { attempts 2 }
    idempotency required
  }

  governance {
    audit required
    evidence required
  }

  confidence {
    threshold 0.8
  }
}

confidence is a threshold family, not a full LLM evaluation or grounding model. Observability is expressed with observe blocks, not an observability policy family in DCL v1.0.

Attachment Targets

Policies may govern capability, effect, outcome, event, and lifecycle boundaries when supported by the compiler.

Composition

Multiple policies can apply to the same boundary. The compiler derives the effective policy envelope, checks family/concern compatibility, detects conflicts, and records obligations in IR.

language dcl 1.0

actor Operator is human

effect PublishInvoice is notification
effect PersistInvoice is persistence

policy InvoiceExecution {
  performance {
    throughput above 100 per minute
  }

  governance {
    audit required
    evidence required
  }

  confidence {
    threshold 0.9
  }
}

policy InvoiceSecurity {
  security {
    authentication required
    authorization required
    encryption required
  }
}

shape InvoiceInput {
  invoiceId: Uuid required
  customerId: Uuid required
}

event InvoicePublished is {
  invoiceId: Uuid required
}

capability PublishCustomerInvoice {
  intent InvoiceInput from Operator

  outcomes {
    InvoiceAccepted
    InvoicePublishDeferred
  }

  effects {
    PersistInvoice
    PublishInvoice after PersistInvoice
  }

  policies {
    InvoiceExecution governs capability
    InvoiceSecurity governs event InvoicePublished
  }

  observe {
    capability duration as invoice_publish_duration
    effect PublishInvoice count failures as invoice_publish_failures
    event InvoicePublished count as invoices_published
    outcome InvoicePublishDeferred count as invoice_publish_deferred
  }

  when {
    PublishInvoice unresolved then InvoicePublishDeferred
    otherwise then InvoiceAccepted
  }
}

Capability

A capability is the main unit of DCL responsibility. It evaluates intent, enforces rules, applies policies, produces outcomes, and may cause effects, emit events, or own lifecycle state.

language dcl 1.0

actor User is human

shape GreetingInput {
  name: Text required
}

capability SayHello {
  intent GreetingInput from User

  outcome GreetingPrepared

  when {
    always GreetingPrepared
  }
}

Intent

Intent is the transport-agnostic expression of a desired business action. It identifies the input shape and actor source for a capability.

Intent must belong to a capability. It does not imply HTTP, synchronous completion, queue semantics, or any specific runtime entry point.

Outcome

An outcome is a finite named result class. Outcomes represent success, rejection, deferral, expiry, failure, escalation, or other meaningful completions without treating failure as an exception by default.

Outcomes may drive lifecycle transitions, observations, policies, and future generated artifacts. The compiler rejects references to undeclared outcomes.

Rule

A rule is a named invariant or business condition. Rules may refer to input fields and named actor roles. Rule expressions prefer human-readable operators such as is true, is present, is less than, and is not equal to.

Rules become meaningful when they participate in outcome causation, usually through a when branch such as a rule being violated.

When

The when block declares explicit outcome causation. It connects rule violations, unresolved effects, unconditional causation, and fallback causation to declared outcomes.

DCL v1.0 does not support succeeded or expired as general when decision words. violated is for rule constraints being breached. Policy constraints use policy-specific words such as denied, fails, exhausted, times_out, open, degraded, or fallback_used when the matching policy concern can produce that state.

when {
  EmailPresent violated then MissingEmail
  SearchKnowledgeBase failed then ToolUnavailable
  policy MinimumAnswerConfidence fails then InsufficientConfidence
  otherwise then AnswerPrepared
}

language dcl 1.0

actor Customer is human

effect PersistRegistration is persistence
effect SendVerificationMessage is notification

shape RegistrationInput {
  email: Email required
  acceptedTerms: Boolean required
}

event VerificationMessageSent is {
  email: Email required
}

capability RegisterCustomer {
  intent RegistrationInput from Customer

  outcomes {
    RegistrationAccepted
    TermsRejected
    VerificationDeferred
  }

  rule TermsAccepted: input.acceptedTerms is true

  effects {
    PersistRegistration
    SendVerificationMessage after PersistRegistration
  }

  events {
    emits VerificationMessageSent
  }

  when {
    TermsAccepted violated then TermsRejected
    SendVerificationMessage unresolved then VerificationDeferred
    otherwise then RegistrationAccepted
  }
}

Lifecycle

A lifecycle describes business progression over time. It has an owner, steps, transitions, optional waits, optional deadlines, optional recovery, and terminal states.

Local Lifecycle

A lifecycle declared inside a capability is owned by that capability. Current syntax prefers semantic phrases such as waits for event and requires decision from over authored kind metadata.

language dcl 1.0

actor Customer is human

shape PaymentInput {
  orderId: Uuid required
  amount: Money required
}

event PaymentReceived is {
  orderId: Uuid required
}

capability CollectPayment {
  intent PaymentInput from Customer

  outcomes {
    PaymentRequested
    PaymentExpired
  }

  when {
    always PaymentRequested
  }

  events {
    emits PaymentReceived
  }

  lifecycle {
    begin AwaitingPayment

    step AwaitingPayment waits for event PaymentReceived {
      deadline 15 minutes causing outcome PaymentExpired
    }

    end Paid
    end Expired

    move AwaitingPayment to Paid
      on event PaymentReceived

    move AwaitingPayment to Expired
      on outcome PaymentExpired
  }
}

Supervising Lifecycle

A supervising lifecycle is owned by one capability and coordinated through contributor capabilities. Contributors may produce outcomes or events that cause movement, but they do not mutate lifecycle state directly.

Supervising lifecycle transitions must declare explicit sources. The compiler validates contributor existence, source outcomes/events, reachability, and unambiguous transition causes where possible.

language dcl 1.0

actor Customer is human
actor WarehouseOperator is human

effect ReserveStockRecord is persistence
effect CapturePaymentRecord is persistence
effect DispatchParcel is notification

shape OrderInput {
  orderId: Uuid required
  sku: Text required
  quantity: Number required
}

shape PickInput {
  orderId: Uuid required
}

event ParcelDispatched is {
  orderId: Uuid required
}

capability ReserveInventory {
  intent OrderInput from Customer
  outcomes {
    InventoryReserved
    InventoryUnavailable
  }
  effect ReserveStockRecord
  when {
    ReserveStockRecord unresolved then InventoryUnavailable
    otherwise then InventoryReserved
  }
}

capability CapturePayment {
  intent OrderInput from Customer
  outcomes {
    PaymentCaptured
    PaymentDeclined
  }
  effect CapturePaymentRecord
  when {
    CapturePaymentRecord unresolved then PaymentDeclined
    otherwise then PaymentCaptured
  }
}

capability ShipOrder {
  intent PickInput from WarehouseOperator
  outcomes {
    ShipmentStarted
    ShipmentBlocked
  }
  events {
    emits ParcelDispatched
  }
  effect DispatchParcel
  when {
    DispatchParcel unresolved then ShipmentBlocked
    otherwise then ShipmentStarted
  }
}

capability FulfilOrder {
  intent OrderInput from Customer
  outcome FulfilmentOpened

  when {
    always FulfilmentOpened
  }

  supervises lifecycle OrderFulfilment {
    identity orderId

    contributors {
      ReserveInventory
      CapturePayment
      ShipOrder
    }

    begin Created

    step Created

    step AwaitingPayment {
      waits for outcome PaymentCaptured from CapturePayment
      waits for outcome PaymentDeclined from CapturePayment
    }

    step ReadyToShip requires decision from WarehouseOperator

    step Dispatching waits for event ParcelDispatched from ShipOrder

    end Completed
    end Failed

    move Created to AwaitingPayment
      on outcome InventoryReserved from ReserveInventory

    move Created to Failed
      on outcome InventoryUnavailable from ReserveInventory

    move AwaitingPayment to ReadyToShip
      on outcome PaymentCaptured from CapturePayment

    move AwaitingPayment to Failed
      on outcome PaymentDeclined from CapturePayment

    move ReadyToShip to Dispatching
      on outcome ShipmentStarted from ShipOrder

    move Dispatching to Completed
      on event ParcelDispatched from ShipOrder

    move ReadyToShip to Failed
      on outcome ShipmentBlocked from ShipOrder
  }
}

Observation

Observations declare metrics and trace points derived from language semantics. They can count outcomes, effects, events, failures, violations, durations, and lifecycle transitions.

Observation declarations are not runtime vendor configuration. They are semantic instrumentation requirements that generated artifacts or runtime projections can use later.

observe {
  outcome AnswerPrepared count as answers_prepared
  effect SearchKnowledgeBase duration as knowledge_search_latency
  effect SearchKnowledgeBase failures as knowledge_search_failures
  capability violations as answer_policy_violations
  lifecycle transitions as support_lifecycle_transitions
}

Rule-specific and policy-specific observation targets are not supported in DCL v1.0. Use capability-level violations for compiler-visible rule or policy violation metrics, and attach policies explicitly for policy decision semantics.

Compiler Diagnostics

The compiler is responsible for semantic correctness, not just syntax. It emits errors for invalid programs and warnings for valid but risky or suspicious programs.

Reference Sources

This page is distilled from the repository design documents for primitive contracts, surface syntax, compiler duties, context visibility/dependencies, policy composition, supervising lifecycles, lifecycle completion semantics, and the accepted v1.0 compiler behavior.