User Events Stream

Fired when a workspace credit total changes (reserve / commit / refund).

Payload-less by design: the FE invalidates the credits query and refetches the authoritative state. Keeps the channel cheap (one short JSON per transition) and frees the publisher from needing to compute workspace totals at emit time.

Fired when a kickoff launches a batch of enrichment row-workflows.

The "started" half of the enrichment lifecycle, symmetric to EnrichmentStatusChangedEvent (the terminal half). Together they make the FE's in-flight set fully server-authoritative: it ADDS the carried rows here and DROPS each one on its terminal event, instead of optimistically inferring "started" from the kickoff HTTP response. That optimistic path held one entry per project_id:field_name and reset it on every new coordinator_workflow_id, so concurrent per-row runs on the same column collapsed onto the latest one (only the most recent row showed enriching). Keying on coordinator_workflow_id here lets each run track independently.

Carries the same coordinates the /in-flight payload exposes (coordinator_workflow_id / field_name / per-row workflow_id + feature_id) so the live-delta path and the resume-snapshot path build identical registry entries. launched_total is the fixed progress denominator (immune to waved fan-out), matching InFlightBatchResponse.

Fired when one enrichment workflow reaches a terminal state.

Unlike CreditStateChangedEvent this is payload-rich. It carries:

• workflow_id — the client registry's key; routes the event to the cell/column it belongs to.
• project_id / enrichment_id / feature_id — the coordinates, so an event for a workflow the client didn't dispatch in this session (e.g. after a reload, before reconcile) can still build a registry entry from the event alone.
• value — on SUCCESS, the persisted EnrichRowResponse-shaped dict ({value, reasoning, citations, state}) built from the SAME db_value written to the sandbox, so the live cell is byte-identical to what a refresh re-reads. None on FAILURE (no value was written).

The terminal-status policy lives on the server (the workflow's own terminal state), not on the client — so the client can no longer drift a transient signal into a false terminal (the bug class this replaces).

Fired after a project view mutation commits (create / update / filter / delete / column change), over the same per-user channel.

Payload-rich + version-stamped, mirroring EnrichmentStatusChangedEvent: the FE applies the carried view(s) straight to its React Query cache without a refetch round-trip, and uses each view's version to discard stale or out-of-order events. Carries only the affected view(s) plus deletedViewIds (not the full list) so the FE merges rather than overwrites siblings.

Fields are camelCase so the SSE endpoint can forward model_dump_json verbatim and the FE reads the same keys it reads off /views.

Fired after a layer metadata mutation commits (create / delete / rename / restyle / recolor), over the same per-user channel — the layer sibling of ViewStateChangedEvent.

Payload-rich + version-stamped: the FE applies the carried layer(s) straight to its React Query cache without a refetch round-trip, and uses each layer's metadata_version to discard stale or out-of-order events. Carries only the affected layer(s) plus deletedLayerIds so the FE merges rather than overwrites siblings.

Unlike views, the nested layers serialize in their snake_case wire shape — LayerModel has no field aliases, and the FE reads the same snake_case keys off GET /projects/{id}/layers through layerMappers.fromApiModel. So no field_serializer is needed here; the default dump is already the wire shape.

Fired when a project's name changes server-side, over the per-user channel.

The trigger today is auto-title generation: a fire-and-forget task that generates a name several seconds into the turn, and can retry on a later message. By then the project is already ready and the FE's creating-project poller has stopped watching it, so without this event the new name only surfaces on the next projects refetch — a manual refresh in practice.

Carries the coordinates the FE needs to patch the projects-list cache in place: projectId to locate the row, name for the display, and titleSource so the cached row matches what a refetch would read. camelCase wire shape, matching ViewStateChangedEvent / LayerStateChangedEvent.

Advisory only — a dropped publish degrades to the FE's reconnect-resync.

Fired when a chat's background summarize_workflow finishes persisting.

Summarization runs as a fire-and-forget DBOS workflow after a turn crosses the context threshold; the turn's complete SSE frame (carrying summarization_task_id) is the enqueue moment, ~50s before the summary actually generates + persists. The original turn's direct stream has closed by then, so this advisory event over the per-user fanout is how the client learns the summary is genuinely done and renders the "summarized" divider.

Advisory only — the durable summary is the source of truth: on reload the FE reconstructs the divider from persisted history (detectSummarization), so a dropped publish degrades to "divider appears on next reload," never a stuck state.

Carries only projectId (camelCase wire shape, matching ViewStateChangedEvent / LayerStateChangedEvent): chats.project_id is UNIQUE (one chat per project), so the project anchors the chat and the FE needs no chat_id to route.

Fired as a background address import advances, and once when it settles.

One event type covers both halves of the import lifecycle — unlike enrichment, which needs a started/terminal pair because a kickoff fans out across many row workflows. An import is a single job, so status distinguishes in-flight from terminal and the client keys every frame on the job's id.

The job's id — never its project_id — is the client registry's key: a project can be imported into more than once, so a project-keyed frame from a previous attempt would be read as progress on its replacement.

Carries the job row itself rather than a hand-picked set of scalars. The terminal frame is the only thing the badge renders before it self-dismisses — well inside the client's 30s reconcile window — so any field the frame omits is a field the user never sees on a settled import. Picking fields by hand meant the settled counts were left off and every finished import reported "0 of N rows imported"; a nested :class:ImportJobSnapshot makes the frame and the polled read the same shape by construction.

The nested job serializes in its snake_case wire shape, like LayerStateChangedEvent's layers: the FE reads the same keys off GET /import/jobs/in-flight, so one client mapper serves both channels.

Advisory only for the fact of settling: import_jobs is the durable truth a reload re-reads, so a dropped publish degrades to the client's 30s reconcile poll.

Fired when the agent moves the map camera to a resolved feature, over the per-user channel — the reply to a "zoom to <address/place/parcel>" request.

Carries the envelope bbox ([minLng, minLat, maxLng, maxLat]) of a feature already in the project's data; the FE fitBounds to it. projectId gates the move to the active project (the per-user stream is not project-scoped). camelCase wire shape, matching the sibling events.

Fire-and-forget / advisory: a dropped publish just means the camera doesn't move — the agent's text reply still names where it went.

Fired after a project's excluded-row set changes (bulk exclude or restore commits), over the per-user channel.

Exclusions are an always-on server-side predicate, so the client holds no filter state to patch — this event tells it the visible row set changed: invalidate the exclusions query and bump the exclusions revision, which purges the SSR grid and re-points tile URLs. It is the only channel through which an agent-driven exclusion reaches an open browser (the agent's removal no longer runs SQL whose affected_layers the client parses).

version is the project's post-bump excl_v counter (None when Redis was unavailable for the bump); the FE treats it as opaque freshness. camelCase wire shape, matching the sibling events.

Advisory only — a dropped publish degrades to staleness bounded by the next refetch or reload; the durable row_exclusions table is the truth.