Augeo AI Docs
Events Dictionary

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.

FamilyClassOwnerStage
uiall observeddesign system1
engagementall measuredAIA platform2
conversationmeasured and observedchat SDK2
recognitionmeasured and observedrecognition domain2
preferenceall measuredIntelligence and Product2
profilemeasured and observedAIA platform2

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.viewed

profile.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 class

null 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.