@package-system

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"
}]
FieldRequiredMeaning
idyesDotted lowercase id, unique in the package. The wire type is derived from the publishing package, so no package can emit another package's events.
titleyesHuman title (at most 80 characters), always rendered as text.
descriptionnoLonger explanation.
subjectyesWhat the event is about; names the src/events/<subject>.ts file that decides who may see it.
dataSchemayesA closed JSON schema for the event's data: "type": "object" with "additionalProperties": false at the root, nested at most four levels.
requires.featuresyesThe feature a reader needs — the feature of the route that serves the same record. A reader without it never receives the event.
notifyno{ "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.
docknoThe 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.

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.

On this page