Origin decoding: show which frontend action started each chain

[robnewton]

What this adds

A way to label each chain of invocations with the frontend action that started it, so observability and the flow console can show "a dealer created a move" next to the database write instead of just the write.

Two parts:

• The originDecoder plugin, which reads an id the frontend sends and turns it into a small object for display.
• Console rendering: a node on the flow canvas showing that action, who did it, and when, plus grouping of chains that came from the same click.

How it works

A frontend sends a short id for the action a user took (say, "dealer creates a move") as the x-b3-traceid header on its Hasura mutation. With Hasura's OpenTelemetry config on, that id arrives in the event payload at event.trace_context.trace_id, and the Hasura source puts it on meta.sourceTraceId.

That id is only for display. It is never the chain's id. Every chain gets its own correlation id (the id that ties a chain of invocations together) minted fresh at the start, whether or not an id came in. This matters for two reasons:

• Frontends send the same id for the same action every time, which is what makes it worth decoding. If that id became the chain id, every unrelated run of that action would collapse into one chain.
• A client should not get to pick a chain's id. It can send any id it wants.

Using it

You write a decode function that turns the incoming id into an object to show, and register the plugin with it. decode is required; eventkit does not ship one, because the meaning of your ids is yours.

The usual way to write decode is a list of the actions your frontends can start, kept in your own code and shared by the frontend that sends the id and the function that decodes it:

export const ORIGIN_ACTIONS = [
  { id: 'act-move-create', action: 'move.create', site: 'dealer-portal', purpose: 'dealer creates a move' },
  // add new ones to the end; never reuse or change an existing id
] as const;
const BY_ID = new Map(ORIGIN_ACTIONS.map(a => [a.id, a]));
export const decodeOrigin = (id: string) => BY_ID.get(id) ?? null;

const kit = createEventKit(hasuraEvent())
  .use(originDecoder, { decode: decodeOrigin })
  .registerEvents([/* ... */]);

decode returns any JSON object to show, or null for an id it does not know (then the plugin does nothing). The object lands at context_data.origin on the first invocation of the chain. Only the first invocation gets one: later steps carry a Hasura-generated trace id, not your action id, so decode returns null for them.

The docs cover the list pattern, a pack-it-into-the-id alternative, sending the header from the frontend, and the safety notes.

The console

When the first invocation of a chain has a context_data.origin, the flow canvas draws a node to its left showing the action, the person who did it (name and role), and when. It carries the ORIGIN marker, since the click started the chain, not the row write. Click it for a drawer with the full decoded object and a link back to the invocation it started. If you give the console a userResolver(email) that returns a name and avatar, it shows those; otherwise it shows the email and initials.

If the decoded object has a clickId (an id the frontend can send that is the same for every chain one click set off), the console groups those chains: one action node stands in front of all the chains that click started, with an edge into each, a small "N chains" count on the card, and a drawer section listing them so you can jump between them. Chains without a clickId each get their own node. The clickId is display-only grouping, like the rest of the object, and each chain keeps its own correlation id.

Options

• originDecoder({ decode }): decode is required. Your function from the incoming id to an object, or null.
• correlationFromTraceId on the hasuraEvent source, default off. Off keeps the trace id out of the chain id (the safe default above). Turn it on only for a trusted caller that sends a real, unique trace id per request that you want to be the chain id.

Try it locally

1. In console/, run node db/local-setup.mjs then npm run seed. The seed puts an origin on some root invocations.
2. Run npm run dev, open a root invocation's flow, and the action node sits to its left. When two roots share a clickId, one node fans into both chains and its drawer lists them.

Checks

Tests, typecheck, typecheck:contracts, build, bundle check, and docs compile all pass, plus the console app build and library build.

Related

Works with sdk PR #662 (Hasura sends the x-b3-traceid through to trace_context.trace_id) and sdk PRs #663 and #664 (the frontend sending the header, and the shared list of actions).

Chain usability round

A second scope on this branch makes the CHAIN (all invocations sharing a correlation id) the primary object in observability and the console. Origin is optional decoration on top: header-less and non-frontend chains get the same chain and health treatment.

Writer and schema

Sources expose meta.correlationMinted, true when an invocation minted its correlation id and false when it inherited one (loop-guard clears it when it adopts an inbound token's correlation). The observability writer reads the settled flag to set is_chain_root truthfully. Root is never inferred from timestamps and does not depend on a decoded origin.

The writer also promotes context_data.origin.action to an indexed origin_action, and on every member write rolls a summary onto the chain's root row: chain_last_activity_at (greatest-wins) and chain_status (flips to errored when any member errored, never back). The rollup is best-effort and never blocks event handling, so a chain's root can read errored even though the root invocation itself completed, because a downstream member failed.

New invocations columns (origin_action, is_chain_root, chain_status, chain_last_activity_at) and their indexes are in console/db/schema.sql. Existing databases apply console/db/schema-delta-chain-rollup.sql before deploying the writer (it lists the columns in its invocation upsert).

Console

• Chains index: the Invocations screen defaults to one row per chain, queried as plain root rows with no group-by, sorted by last activity. Rows show the origin chip when present (or the root event otherwise), user, chain status (row color follows the chain, so a root that itself succeeded under an errored chain reads errored), last activity, and per-page invocation count and span. A persistent errors-only toggle (?errors=1) and a per-action filter (?action=) are URL params, and a view toggle keeps the flat all-invocations table.
• Permalink: the flow page accepts ?correlationId= alongside ?invocationId=, resolving the chain root and rendering the same diagram. This is the stable deep link external tools point at.
• Search: resolves a full correlation id, a bare invocation UUID, or a fuzzy fragment to the right flow, plus an origin-action typeahead group.
• Dashboard: leads with an errored-chain count and trend against the previous window, a needs-attention feed of recent errored chains (each one click from its flow), and a top-origin-actions table with per-action errored rate; the existing charts move below.

Docs: docs/chain-observability.md. The new GraphQL operations are hand-scoped into console/src/types/generated.ts (the console schema drifts, so a blind regen is unsafe).

Verified

Root typecheck and 333 backend tests pass. Console builds. Verified headless (puppeteer + local Chrome) against the seeded local obs DB: chains default view, errors-only view, per-action URL filter, reordered dashboard, and a ?correlationId= permalink that renders a chain whose root completed but whose child failed as errored.

Origin node generalized

A decoded origin is now any registered entry point, not only a human click. The console derives the origin node's kind label from the decoded object's optional trigger field (user → "User action", webhook → "Webhook", schedule → "Scheduled", system → "System", absent/unknown → a neutral "Origin"), through one shared helper used by the node, the detail drawer, and the breadcrumb. The avatar/name row renders only for origins that carry a person; webhook and system origins have no identity, so that row is omitted, and the drawer shows trigger as a fact. Everything still derives from the decoded object. The seed gains a webhook-triggered chain so the non-user card renders in dev. Verified headless: the webhook chain renders a "Webhook" origin card with no avatar row.

What it looks like

Chains index, the default view: one row per chain, with the origin action chip when present, chain status, last activity, and per-chain invocation count and span.

Errors-only toggle: the persistent, URL-addressable filter to chains that errored anywhere.

Search resolves origins too: typing an origin action shows an origin-action suggestion group over the indexed column.

The dashboard leads with health: an errored-chain count with trend, then the needs-attention feed of recent errored chains.

The flow permalink: opening ?correlationId= resolves the chain root and renders the whole chain. Here the root completed but a downstream member failed, so the chain reads errored.

Origins are entry points generally, not only clicks: a webhook-triggered chain renders a "Webhook" origin card with no user row.

Expected-flow overlay (per-invocation)

The flow canvas can now overlay what a run was supposed to do on top of what it did do. The host wrapper injects an expectedFlowResolver (same pattern as userResolver); it returns an ExpectedFlowGraph, which is toFlowGraph()'s output plus optional metadata, so a producer (the registry codegen) can emit it as plain JSON with no console-specific fields. Node ids stay name-derived so observed and expected line up.

Toggle it with "Expected flow" in the toolbar or the X hotkey; the choice is remembered in localStorage, and the toggle only appears when a resolver is wired. It is display only, per invocation, and never a pass/fail gate. An invocation with no resolved flow (no resolver, null, or error) renders exactly as today.

• Expected but not observed steps render as dashed, muted ghost nodes, same shape as the real ones.
• Observed but not expected steps keep their node and get a small off-contract badge.
• Matched steps are unchanged.

The user-action drawer also gains an "Expected events" section: when a decoded origin carries expectedEvents, each name is checked against the events observed anywhere in the loaded chain (a check when seen, a muted dashed marker when not).

Contract type and semantics are in docs/console-expected-flow-overlay.md.

Overlay on: the root's observed move.create.requested sits above a dashed ghost for the expected-but-missing move.audit.recorded, and downstream steps the flow doesn't declare carry an off-contract badge.

Overlay off: the same chain, identical to today.

The user-action drawer's expected-events section: two observed (check), one never observed (dashed miss).

🤖 Generated with Claude Code

https://claude.ai/code/session_011DWPVMqEudqB86CxtHWWVW