Events
events[] — the moments a native package declares a person should hear about, delivered as notifications by the platform.
A native package declares the moments a person should be told about — a run failed, a sync stopped — and the platform turns each published event into a notification for the people it concerns. The package builds no notification UI or storage of its own, and every event rides the platform's one realtime connection.
Declaring an event
"events": [{
"id": "report.failed",
"title": "Report failed",
"subject": "report",
"dataSchema": {
"type": "object",
"additionalProperties": false,
"properties": { "reportId": { "type": "string", "maxLength": 128 } }
},
"requires": { "features": ["acme.reports.read"] },
"notify": { "default": "on", "tone": "error" },
"dock": "acme-reports"
}]| Field | Required | Meaning |
|---|---|---|
id | yes | Dotted lowercase id, unique in the package. The wire type is derived from the publishing package, so no package can emit another package's events. |
title | yes | Human title (at most 80 characters), always rendered as text. |
description | no | Longer explanation. |
subject | yes | What the event is about; names the src/events/<subject>.ts file that decides who may see it. |
dataSchema | yes | A closed JSON schema for the event's data: "type": "object" with "additionalProperties": false at the root, nested at most four levels. |
requires.features | yes | The feature a reader needs — the feature of the route that serves the same record. A reader without it never receives the event. |
notify | no | { "default": "on" | "off", "tone": "info" | "success" | "warning" | "error", "clears"?: [ids] }. Omitted means not a notification unless a person follows it. clears names this package's own event ids the event resolves: a reader allowed to see it has their unread rows of those types about the same subject marked read. |
dock | no | The id of one of the package's own kind: "dock" surfaces; the unread count of that dock entry is kept from these events. |
Each subject needs a source file, src/events/<subject>.ts (compiled to
dist/src/events/). It exports subject, a required visible(event, session, state) predicate — may this person see an event about this subject?
— and an optional bridge(publish, state) that subscribes to the package's own
internal events, calls publish({ event, subjectId, projectId, data, audience }) and returns its unsubscribe. A subject without a predicate has every event
dropped: visibility is deny-by-default.
An event is a signal, never content. data holds ids and fixed codes,
validated against dataSchema and capped at 4 KiB — never an error message, a
path, a transcript or anything the subject's route would refuse to show. Two
optional data keys shape the notification row when the schema declares them:
title (a string shown before the declaration title) and nav ({ widgetType, initialState? }, the row's navigation target). A publish that breaks the
schema throws, so a producer bug is loud rather than silently dropped.
The delivered envelope uses the CloudEvents 1.0 attribute names (id, type,
source, subject, time, data); the events[] declaration itself is a
Neuralis shape. The field is honored for native packages only; on any
other package it is a warning and is dropped at load. At most 64 events per
package.
Where to read next
The subject file is compiled like any other package module — see the
directory contract. A package that wants a
person to act on an event usually pairs it with a dock entry
(App surfaces) and the route that serves the
underlying record (Routes), gated by the same feature
the event's requires.features names.