Augeo AI Docs
Events Dictionary

Landing stages

What you can implement today, and what is agreed but not yet emittable.

The short version

Everything in the dictionary is v1. Every $id is published and every shape is frozen for v1. What differs is when each part is implemented.

StageLands inOpensLifecycle
1 · design systemthe design system packagenowstable
2 · SDKthe chat SDK and the events runtimewhen stage 1 has shippeddefined
3 · hostthe consuming applicationwhen stage 2 has shippeddefined

What defined means, and what it does not

defined means: the $id is published, the shape is agreed and frozen for v1, the registry entry exists, the validator enforces it, and codegen generates a type for it. What has not happened is the implementation — there is no emitter, because the layer that would emit it is being built after the one below it.

It does not mean provisional, under review, or likely to change.

You mayStage 1 (stable)Stage 2 / 3 (defined)
Import the typesyesyes
Validate against ityesyes
Generate code from ityesyes
Review ityesyes
Emit ityesnot yet
Bill on ityesno
Forward it externallyyesno

If a stage-2 shape turns out to be wrong before its stage opens, that is an ordinary versioning event — a new payload version, one name affected — not the stage doing its job.

Why this order

Dependency, in all three cases. Not preference, and not a release train.

The design system goes first because it owns the state space. The consequential call in this architecture is that interaction state lives in the component layer, which is what makes it impossible rather than merely discouraged for a control to announce a save that was never confirmed. A claim like that is worth what its implementation is worth, and a contract nobody has built against is a contract nobody has tested.

The SDK goes second because enrichment needs something to enrich. Eight of the measured names are derived from an observed render, and a derived name cannot be minted before the thing it derives from exists.

The host goes third because it cannot answer an acknowledgement nothing sends it. The ack round trip is what turns a request into a resolved state, and the host's half has no meaning until the SDK's half runs.

What is in stage 1

Frozen as of this release, additive change only:

  • the compact envelope
  • both state spaces — SlotPhase and EffectPhase
  • the shared enumerations
  • the item reference
  • the resolved-state and slot-declaration contracts
  • the augds context namespace
  • all eleven ui names

That is the whole surface a component needs in order to emit what it observed and render the phase it was handed.

import { namesForStage } from "@kigo-digital/augeo-events";
import type { Stage1EventName } from "@kigo-digital/augeo-events";

namesForStage(1); // the eleven names, at runtime

// At compile time — a stage-2 name here does not compile:
function emit(name: Stage1EventName) {
  /* … */
}

The rule that makes staging safe

An earlier-stage artifact may reference a later-stage one, but only in an optional position.

The envelope is the case that matters. It is stage 1 and it references the SDK and platform context namespaces, which are stage 2. That is deliberate: the envelope reserves those slots at v1 and requires none of them, which is what lets a design system emit a complete, valid event today with only its own namespace filled in.

Making any of them required would invert it — stage 1 would be unsatisfiable until stage 2 shipped. So it is checked rather than intended: CI walks every reference, and a lower-stage schema that puts a higher-stage reference behind a required key is a build failure.

Checking a stage at runtime

import { EVENTS, STAGES } from "@kigo-digital/augeo-events";

EVENTS["com.augeo.preference.declared"].stage; // 2
EVENTS["com.augeo.preference.declared"].lifecycle; // 'defined'

STAGES.find((s) => s.stage === 1)?.frozen; // true

When a stage opens

Every artifact carrying that stage moves from defined to stable in one reviewed change — the schemas, the registry entries and the affected profiles together. CI asserts the two halves agree, so they cannot drift apart.

Watch the package's release notes: a stage promotion is a major version and says so.