Audit event routing

Every published workflow whose trigger receives an event type starts on each event of that type, subject to its own filter. The routing audit lists, per event type, the workflows that start together, what they do outside their run, and how many events of the type arrived over the last 7 days. It reads the API and, optionally, the definition store and the run index; it writes nothing (apps/api/scripts/routing-audit.ts, logic in apps/api/src/server/routing-audit.ts).

For one workflow at a time, the console shows the same information: the filter panel lists the other workflows that start on the event, and the publication confirmation repeats it. The Routing screen (« Routage », /routing) lists every event type with its workflows. The audit covers the whole instance in one report that you can keep.

When to run it

Before upgrading to a release that changes event routing, and again before rolling it back. See Upgrade the platform, which says where the release notes of such a release are.
When reviewing an instance where several workflows share event types.

Prerequisites

A checkout of the repository at the release of the API you audit, with its dependencies installed (pnpm install): before an upgrade, the release that runs; before a rollback, the release you roll back from. The script reads the deployed API over HTTP. It takes the routing key of each workflow (eventType, pinned) from GET /api/workflows, as the proxy derives it. It has no fallback for an API of another release: on a response without these fields it stops with Audit impossible : « <file> » : GET /api/workflows ne sert pas « pinned ». Lancer le script de la version de l'API auditée.
HTTP access to the proxy of the instance.
Optionally, read access to the definition store (Postgres) and to the run index. The script opens a read-only transaction on each and rolls it back.

Run the audit

API_URL=https://meridian.example.org \
DEFINITION_STORE_URL=postgres://… \
RUN_DB_URL=postgres://… \
pnpm --filter @meridian/api run routing:audit

Input	Default	What the audit reads	Without it
`API_URL`	`http://localhost:4000`	`GET /api/workflows` (published workflows only) and the spec of each, `GET /api/catalog`, `GET /api/connections/protocols` and `GET /api/connections`: the enabled inbound connections, the bindings each one enables, and the feeds of the pulled connections	—
`DEFINITION_STORE_URL`	unset	The order of the active set, as the proxy lists it (`ORDER BY slug` in the database collation)	The audit assumes the order of the slugs by code point, and says so where the order matters
`RUN_DB_URL`	unset	`sqlite:<path>` or `postgres://…`: distinct events per type over the last 7 days	`volume inconnu`
`--json`	text report	Prints the audit as JSON instead of the text report	—

A relative path (RUN_DB_URL=sqlite:<path>) is read from the directory where you type the command, not from apps/api. When the inbound connections cannot be read, the script prints Connexions entrantes non lues : … on stderr and the report says what it did not check (Connexions entrantes non lues : bindings non vérifiés.). A failed API call stops the script with Audit impossible : … and exit code 1.

The same variables are listed in Environment variables.

Read the report

The text report is in French. It starts with a count: Audit du routage : <n> types d'événement reçus, <m> reçus par au moins deux workflows publiés.

Then one block per event type that at least one published workflow receives. Triggers with their own address (webhook, schedule, call by another workflow, EAI connection) are not listed: each of their events designates one workflow.

## <Type> : <n> workflows, <volume>: the volume counts the distinct events of the type that started at least one run in the last 7 days.
One line per workflow, in the order of the active set: - <file> : filtre : <expression>, sans filtre, or filtre en erreur : expression vide for an empty filter, which starts the workflow on no event; then effets : and the catalogue labels of its nodes with an effect outside the run (sinks, human tasks, agents, sub-workflow calls), or aucun. même type d'effet qu'un autre workflow : names the sink and human-task node types that another workflow of the same type also uses: an event of that type produces that effect twice.

For a type with two workflows or more, the block continues with the routing of the releases before fan-out, where one workflow per event started (the first true filter in the active-set order, else the workflow without a filter). Those releases treat an empty filter as no filter, and these lines follow their rule:

Routage exclusif d'avant : …: the filters in that order and the workflows without a filter.
Sélecteurs qui reproduisent le routage exclusif :: one filter per workflow that, set on each of them, makes only the workflow of the exclusive routing start. inchangé and reste sans filtre mark the workflows to leave as they are.
Retour arrière bloqué : <n> workflows sans filtre (…). Dépublier ou filtrer. replaces the proposal when two workflows of the type have no filter: a release with exclusive routing refuses to start with them.

The ## Même fait section lists what may carry one fact as several events:

an EAI connection whose bindings produce several event types that workflows receive: a message accepted by several of these bindings starts the workflows of each type;
an event type produced both by a feed of an enabled pulled connection (a binding it enables, resolve bindings aside) and by an EAI connection.

The report ends with the limit of the proposed filters: when a filter raises an error on an event, its negation in the other workflows' proposals raises too, so those workflows do not start either.

Act on the report

For each event type that starts several workflows, decide:

accept that each of them starts;
set a filter on some of them, in the console (see Choose which events start a workflow); the proposed filters reproduce the exclusive routing;
or unpublish the ones that must not start.

Keep the report with the release notes of the upgrade. After publishing changes, run the audit again. The proxy also logs, each time it loads the workflows, one line per event type received by at least two workflows: Événement <type> : <n> workflows démarrent (<files>)., followed by Effets du même type : … when they share effect types.

Upgrade the platform — the rollout rules for a release that changes event routing.
Events and triggers — why every workflow that receives an event type starts.
Choose which events start a workflow — filters, default filters and the Routing screen.
Run index database — the table the volume is read from.