Event names
The six families, how a name is composed, and how to look one up.
How a name is composed
com.augeo.<family>.<segment>(.<segment>)*A segment is lower-case alphanumeric and may contain underscores inside it — which
is what admits com.augeo.conversation.turn.first_token. Hyphens are not
permitted, and neither is an underscore at a segment boundary.
The CloudEvents form appends the payload version: com.augeo.ui.slot.declared.v1.
The families
Do not copy a name count from this page. Counts copied into prose go stale the
moment a name is registered. Looking a name up is the count:
namesForFamily and EVENTS.
| Family | Class | Owner | Stage |
|---|---|---|---|
ui | all observed | design system | 1 |
engagement | all measured | AIA platform | 2 |
conversation | measured and observed | chat SDK | 2 |
recognition | measured and observed | recognition domain | 2 |
preference | all measured | Intelligence and Product | 2 |
profile | measured and observed | AIA platform | 2 |
engagement.redemption.completed is the one name at stage 3: it requires a
server-confirmed transaction record, and no browser can supply one.
The profile names are registered at stage 2 with lifecycle defined.
Registration is not a stage opening. A defined name may be validated and
generated into types. It is not emittable, billable, or forwarded to Layer 2 or
Layer 3 until its stage opens.
ui — what a component observed
component.rendered component.viewed action.pressed effect.requested
effect.settled media.failed slot.declared slot.filled slot.settled
slot.failed slot.dropped
All observed, all stage 1, all frozen. These are mechanical facts a component
can assert about itself with nothing declared about what they mean.
engagement — the commerce funnel
component.loaded item.viewed item.detail.viewed item.activated
item.saved item.unsaved cart.item.added cart.item.removed
cart.item.updated redemption.started redemption.completed
GA4-ecommerce aligned where a true analog exists. Note that item.detail.viewed
holds view_item — in GA4 that means a detail view — while item.viewed, a
per-item impression inside a list, projects to the custom theo_item_impression.
redemption.started stays a client-emittable name. A host may suppress that
client publish when the platform records the start server-side. Other hosts
may still publish it.
conversation — the assistant runtime
Measured: session.started session.ended message.sent message.received
turn.started turn.settled tool.invoked tool.settled prompt.selected
handoff.offered handoff.accepted decline.shown feedback.given
launcher.viewed error.shown
Observed: turn.first_token turn.stalled turn.wait_crossed
connectivity.lost connectivity.restored
The five observed names are transport facts the runtime asserts with nothing
declared about them, so they stay local and have no external projection.
connectivity.lost and .restored are a pair, because the
auto-retry-on-reconnect recovery is unusable if only the loss is observable.
error.shown is a failure the member was shown, which is a different number
from a server-side error count and always will be. It must not be conflated with
decline.shown — a decline is the assistant working correctly and refusing on
policy.
recognition — directional, multi-actor
Measured: given received — paired via correlation.interactionId, with
actorRole in the occurrence. One act, two events, two opaque participant
references.
Observed: initiated — the member opened the recognition composer from a
profile. Class is per name, not per family.
com.augeo.recognition.initiated
The composer opened from a profile control. origin is profile. entry is
overview or shoutouts, the two controls that open the composer. It fires
when the composer opens. It does not fire for a keystroke, a close with no
send, or the send. The send stays on com.augeo.recognition.given and
com.augeo.recognition.received. It does not carry the message. It may carry
counterpartRef, an opaque reference of the profile participant, the same
kind as on recognition.given. There is no committed write to wait for. There
is no default destination projection. A later optional field is free.
{"origin":"profile","entry":"overview","counterpartRef":"pref_7ce20b19"}
{"origin":"profile","entry":"shoutouts"}The press profile.shoutout.give stays com.augeo.ui.action.pressed. That
press is the gesture. initiated is the fact that the composer opened.
preference — declared, never inferred
quiz.shown quiz.started quiz.step.viewed quiz.step.completed declared
A declared preference is the member telling you something about themselves. It is not commerce and it is not conversational transport, which is why it is its own family: the same capture belongs on an onboarding page or a preference centre, neither of which has a conversation.
There is deliberately no quiz.completed. The last declaration in a run is the
completion, marked by isLastStep.
A values quiz stays on these names and on preference.declared. Saving the compass
result is not a quiz event and not a new declaredVia. It is
profile.updated with field: "value_compass".
profile — a presented profile, and committed writes
viewed updated media.added prompt.answered reaction.changed
viewed is observed. The four writes are measured. All five are stage 2,
lifecycle defined, owned by AIA platform. None has a default destination
projection. None creates an acknowledgement obligation. The ack belongs to a
write request, and viewed is not a write.
The four write names are outcomes of a committed write. THEO emits each after persistence succeeds. A button press is not those names. A later optional field is free.
Submitting a recognition is com.augeo.recognition.given and
com.augeo.recognition.received. Opening the composer is
com.augeo.recognition.initiated. Neither is a profile name.
com.augeo.profile.viewed
A profile was shown. One name covers a profile view and an own profile view.
relation is self when the viewer owns the presented profile, and peer
when the viewer does not. It fires once when the profile is presented, not
once per widget. It does not carry a display name, a photo, or bio text. It
may carry profileRef, an opaque participant reference of the profile that
was shown, the same kind of reference as counterpartRef on
com.augeo.recognition.given. It is not com.augeo.engagement.item.viewed
and it is not com.augeo.engagement.item.detail.viewed. A profile is not a
catalogue item. There is no committed write to wait for.
{"relation":"peer","profileRef":"pref_7ce20b19"}
{"relation":"self"}com.augeo.profile.updated
The owner saved or cleared one field that is not a call to action. kind is
effect. field is pronouns, pitch, about, chips, photo, or
value_compass. operation is set or clear. chips may carry an optional
shelfId. The saved text, the photo, and the chip labels do not travel.
{"field":"about","operation":"set"}
{"field":"value_compass","operation":"set"}
{"field":"chips","operation":"clear"}com.augeo.profile.media.added
The member added or removed one movie, television show, book, or music title.
kind is effect. shelf is movies, tv, books, or music. operation
is add or remove. sourceProvider and sourceId are optional opaque ids.
The title does not travel.
{"shelf":"movies","operation":"add","sourceId":"title_01"}
{"shelf":"tv","operation":"remove"}com.augeo.profile.prompt.answered
The owner answered or cleared one Fun Facts prompt. kind is effect.
promptId is a nonempty opaque id. operation is set or clear. The
question and the answer do not travel.
{"promptId":"fun_fact_01","operation":"set"}
{"promptId":"fun_fact_01","operation":"clear"}com.augeo.profile.reaction.changed
A colleague added or removed a reaction on a Fun Facts answer. kind is
interaction. It is not a shoutout. promptId is a nonempty opaque id.
operation is add or remove. emojiCode matches
^[a-z0-9]+(?:_[a-z0-9]+)*$, for example thumbs_up. The answer does not travel.
{"promptId":"fun_fact_01","operation":"add","emojiCode":"thumbs_up"}A profile section render stays com.augeo.ui.component.viewed. A press stays
com.augeo.ui.action.pressed. Do not use engagement.item.viewed or
engagement.item.detail.viewed for a profile. This family does not add a
profile allowlist to any consumer profile.
Writes are worked in examples/14-profile-mutations/. The presentation and
the composer open are worked in examples/15-profile-observations/. The send
pair is worked in examples/06-recognition-directional/.
Derived names
Eight measured names are minted from an observed render one layer up, with
correlation.causationId pointing back at it. The observed event stays where it
is.
ui.component.viewed → engagement.item.viewed
ui.component.viewed → engagement.item.detail.viewed
ui.component.viewed → conversation.launcher.viewed
ui.component.viewed → preference.quiz.shown
ui.component.viewed → preference.quiz.step.viewedprofile.viewed is not on this list. A profile is not a catalogue item, and a
section impression stays ui.component.viewed.
Deleting the observed half is not an optimisation. It is how a design system loses the ability to test its own viewability logic, and how an audit loses the ability to re-derive a measured count from raw signals.
Looking a name up
Don't derive facts from the name string. The registry knows them:
import {
EVENTS,
namesForFamily,
namesForStage,
ga4EventFor,
} from "@kigo-digital/augeo-events";
EVENTS["com.augeo.engagement.item.saved"];
// { family: 'engagement', class: 'measured', kind: 'effect', stage: 2,
// lifecycle: 'defined', schemaId: '…', ga4: { event: 'add_to_wishlist', kind: 'standard' }, … }
namesForFamily("preference"); // the 5 preference names
namesForStage(1); // the 11 design-system names
ga4EventFor("com.augeo.ui.action.pressed"); // null — observed names have none, by classnull from ga4EventFor is an answer, not a gap. The eleven ui names, the
observed conversation names, profile.viewed, and recognition.initiated
are local and would swamp an analytics property with no analytical gain. The
profile writes return null because they have no default destination
projection.
Type-level subsets
import type {
RegisteredEventName,
Stage1EventName,
ObservedEventName,
MeasuredEventName,
} from "@kigo-digital/augeo-events";Stage1EventName is the useful one for a design system: it constrains a function
to exactly the eleven names that layer may emit, at compile time.