# Events (https://docs.neuralisapp.com/package-system/events)

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](https://docs.neuralisapp.com/enterprise/multi-tenancy.md#notifications) 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 [#declaring-an-event]

```json
"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 [#where-to-read-next]

The `subject` file is compiled like any other package module — see the
[directory contract](https://docs.neuralisapp.com/package-system/directory-contract.md). A package that wants a
person to act on an event usually pairs it with a dock entry
([App surfaces](https://docs.neuralisapp.com/package-system/app-surfaces.md)) and the route that serves the
underlying record ([Routes](https://docs.neuralisapp.com/package-system/routes.md)), gated by the same feature
the event's `requires.features` names.
