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.
| Stage | Lands in | Opens | Lifecycle |
|---|---|---|---|
| 1 · design system | the design system package | now | stable |
| 2 · SDK | the chat SDK and the events runtime | when stage 1 has shipped | defined |
| 3 · host | the consuming application | when stage 2 has shipped | defined |
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 may | Stage 1 (stable) | Stage 2 / 3 (defined) |
|---|---|---|
| Import the types | yes | yes |
| Validate against it | yes | yes |
| Generate code from it | yes | yes |
| Review it | yes | yes |
| Emit it | yes | not yet |
| Bill on it | yes | no |
| Forward it externally | yes | no |
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 —
SlotPhaseandEffectPhase - the shared enumerations
- the item reference
- the resolved-state and slot-declaration contracts
- the
augdscontext namespace - all eleven
uinames
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; // trueWhen 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.