DSL Overview

The Causet DSL is a set of YAML files (.causet extension) that define your application: entity state, events, commands, projections, queries, relationships, workflows, listeners, and optional AI sections (providers, prompts, decisions, memories). The compiler reads these files and produces the runtime IR that Causet services execute.

Author in .causet files only. Do not hand-edit causet.product.yaml or the compiled core YAML files — those are compiler output.

File Layout

my-app/
  app.causet                              ← root manifest
  states/
    user.state.causet
    artist.state.causet
  events/
    concert.events.causet
  actions/
    concert.actions.causet
  projections/
    concert.projections.causet            ← optional
  queries/
    concert.queries.causet                ← optional
  relationships/
    concert.relationships.causet          ← optional
  listeners/
    concert.listeners.causet              ← optional
  sagas/
    concert.sagas.causet                  ← optional
  resources/
    catalog.resource.causet               ← optional
  commit_envelopes/
    transfer.envelope.causet              ← optional

Root manifest (`app.causet`)

dsl_version: 1
app: my_app
 
includes:
  states:            [./states/**/*.state.causet]
  events:            [./events/**/*.events.causet]
  actions:           [./actions/**/*.actions.causet]
  projections:       [./projections/**/*.projections.causet]
  queries:           [./queries/**/*.queries.causet]
  relationships:     [./relationships/**/*.relationships.causet]
  listeners:         [./listeners/**/*.listeners.causet]
  sagas:             [./sagas/**/*.sagas.causet]
  resources:         [./resources/**/*.resource.causet]
  commit_envelopes:  [./commit_envelopes/**/*.envelope.causet]
  providers:         [./providers/**/*.providers.causet]
  prompts:           [./prompts/**/*.prompts.causet]
  decisions:         [./decisions/**/*.decisions.causet]
  memories:          [./memories/**/*.memories.causet]

Required top-level keys (after assembly):

Key	Required	Description
`dsl_version`	yes	Must be `1`
`app`	yes	App ID: `^[a-z][a-z0-9_]*$`, max 64 chars
`state`	yes	At least one entity definition
`events`	yes	At least one event definition
`actions`	yes	At least one action definition

Optional sections: resources, commit_envelopes, sagas, projections, relationships, queries, listeners, providers, prompts, decisions, memories.

See AI & Decisions for providers, prompts, decisions, and memories.

Single-file mode

If app.causet has no includes, all sections go in one file. Valid for small apps or prototypes.

Compile

# Multi-file app folder (recommended)
causet build compile --runtime path/to/my-app --out build/tmp-out
 
# Legacy single YAML file
causet build compile --runtime path/to/causet.product.yaml --out build/tmp-out

Outputs:

Artifact	When produced
`causet.runtime.json`	Always
`causet.projections.json`	When projections or queries are defined
`causet.decisions.json`	When `providers`, `prompts`, `decisions`, or `memories` are defined

See AI & Decisions for the decisions IR.

Next steps

Top Level Elements — state, events, actions, projections, queries, and more
Operations — every op: documented

Forensics CLI Overview