.evt

Event contract

Versioned events, channels and subscriptions

Validated

No in-tree backend — the artifact is validated and committed, not consumed.

What the system publishes and who reacts: versioned event contracts, channels, and subscriptions with their binding rules.

Why it exists

What .evt is for

An .evt file declares the contracts: events with typed payload fields and a free-form version string, the channels that publish them, and the subscriptions that deliver event sets to named consumers.

It is deliberately transport-independent — nothing about brokers, wire encodings or delivery is written down, and webhook targets stay runtime data. Payload field types resolve against the imported .mox domains, so a misspelt type is a compile error; a subscription when filter is typed boolean against every event in the subscription’s list, because a filter is a per-event routing decision.

Vocabulary

What it models

The concepts .evt declares, and what each one means to the compiler.

event … version "…": A named contract with typed payload fields. The version string is pinned verbatim and carries no ordering semantics — consumers decide what it means.
governance lines: owner, classification, retention and pii [ … ] inside an event body: verbatim labels the driver never interprets.
cloudEvents { … }: Declared type, source and optional subject attributes. Once the block is present they are authoritative for a downstream generator.
channel: A named channel and its publishes membership, optionally of <scope>: the topic-template dimension its topics are parameterized by.
subscription: The events, the one consumer, an optional scope, an optional when filter, and an optional delivery policy.
when (…): A raw phero-expr filter, typed boolean against every subscribed event. A field absent from any of them is an error by design.
delivery { … }: mode (at_most_once, at_least_once, effectively_once) plus attempts, backoff, timeout and a dead-letter channel declared in the same file.
payload types: Any declared domain kind: class, enum, datatype, interface or vocabulary.

Source

A working example

Quoted from the example this page's artifact was compiled from — not a snippet written for the website.

Lines 14–42 of examples/support/support.evt, reproduced byte for byte, read from the file at build time:

examples/support/support.evt · lines 14–42

event RefundRequested version "1.1.0" {
    ticketNo: String;
    refundCents: int;
}

event RefundApproved version "1.0.0" {
    ticketNo: String;
    refundCents: int;
}

event TicketResolved version "1.0.0" {
    ticketNo: String;
    state: TicketState;
}

channel tickets {
    publishes TicketRaised;
    publishes TicketResolved;
}

channel refunds {
    publishes RefundRequested;
    publishes RefundApproved;
}

subscription refundDesk {
    events [ RefundRequested RefundApproved ]
    consumer refund_approval_service
}

Two versioned events, the two channels that publish them, and one of the two subscriptions — the refund desk consumer. The same file declares `TicketRaised`, `TicketResolved` and an analytics subscription.

The whole file is CI-tested: pherolang check examples/ checks every surface in the tree, and the example harness compiles each one on every run. What you see above is the input to the artifact below.

Neighbours

How it relates to the other surfaces

Events are contracts over the domain, not a model of it: payloads resolve against .mox, and .dmn decisions publish to them with emits — the edge is one-way, so an .evt file never references a decision model. .uc uses an event only as a message payload type; its occurrences are scenario-local lifetime points, never events. In .cmmn, a case reacts to case-file transitions, so the event contracts stay the wider integration vocabulary.

Read alongside

Commands

How to compile and validate

Three commands, one file. They run from the repository root against the example on this page.

bash

pherolang check examples/support/support.evt
pherolang ir examples/support/support.evt -o site/data/artifacts/evt.json
pherolang artifact check site/data/artifacts/evt.json

check parses, resolves, validates and type-checks the file and printsOK examples/support/support.evt. ir writes the artifact and prints nothing on success. artifact check then validates the serialized JSON on its own — no model, no import resolution, no compiler — and prints OK site/data/artifacts/evt.json.

Directories work too: pherolang check examples/ enters project mode and checks every supported surface under the tree, each file's imports resolving from the snapshot.

Artifact

What it produces

One versioned JSON artifact, emitted by the compiler and consumed by whatever reads this surface.

One EventModel: the events with their payload fields and governance lines, the channels, and the subscriptions with their consumers.

The artifact is site/data/artifacts/evt.json, and it is committed here exactly as the released pherolang binary emits it. Its top-level shape:

events4 entries
channels2 entries
subscriptions2 entries

Jump to the compiled artifact

Provenance

formatVersion = 2: The compatibility gate. A reader accepts this number or refuses the file.
pheroVersion — not present: This standalone surface artifact is versioned on its ownformatVersion; only the domain model artifact carries the compiler-version stamp.
2,796 bytes: 148 lines, two-space indented, in the file's own key order.

The compiled artifact

The first 40 of 148 lines, verbatim — the exact bytes pherolang ir writes, not a hand-written sample. The slice stops at a JSON boundary; the ellipsis marker is outside the JSON, and the full file is site/data/artifacts/evt.json.

artifacts/evt.json · lines 1–40

{
  "formatVersion": 2,
  "events": [
    {
      "name": "TicketRaised",
      "version": "1.0.0",
      "fields": [
        {
          "name": "ticketNo",
          "type": {
            "type": "primitive",
            "value": "string"
          }
        },
        {
          "name": "title",
          "type": {
            "type": "primitive",
            "value": "string"
          }
        },
        {
          "name": "state",
          "type": {
            "type": "enum",
            "value": {
              "package": "nz.example.support",
              "name": "TicketState"
            }
          }
        },
        {
          "name": "internal",
          "type": {
            "type": "primitive",
            "value": "boolean"
          }
        }
      ]
    },

… 108 more lines in site/data/artifacts/evt.json

Regenerate it from the repository root — the second command validates the serialized bytes with no compiler in the loop:

bash

pherolang ir examples/support/support.evt -o site/data/artifacts/evt.json
pherolang artifact check site/data/artifacts/evt.json

The whole data directory is regenerated by node scripts/sync-model.mjs (run from site/) with the released binary; CI fails on a one-byte difference.

Reference

Documentation

The normative reference for this surface, rendered from the repository's own documentation.

docs.pherolang.com

Event contract reference

The complete .evt reference — vocabulary, grammar, validation rules, artifact wire format, and the CLI contract.

Generated from docs/EVENTS.md in the repository. The page above summarises it; the reference is normative.