Event Envelope Reference
This document describes the vendored machine-facing contract enforced by
src/specify_cli/core/upstream_contract.json
and specify_cli.core.contract_gate.validate_outbound_payload().
The current contract version is 3.0.0.
Canonical Terms
Mission Typeis the reusable blueprint key, serialized asmission_type.Missionis the tracked item underkitty-specs/<mission-slug>/. Its canonical machine identity ismission_id(a ULID). The human-readablemission_slugand the display-onlymission_numberare serialized alongside it for context, but selectors and event routing usemission_id.Mission Runis the runtime/session concept. It is not serialized as tracked-mission identity.
See Mission ID Canonical Identity Migration for the rationale and ADR 2026-04-09-1.
Core Envelope
The upstream event envelope requires these top-level fields:
| Field | Required | Notes |
|---|---|---|
schema_version | Yes | Must equal 3.0.0. |
build_id | Yes | Producer build identifier. |
aggregate_type | Yes | Allowed: Mission, WorkPackage, MissionDossier. Forbidden: Feature. |
event_type | Yes | Event name for the emitted record. |
Forbidden top-level fields in the envelope:
feature_slugfeature_number
Mission-Scoped Payloads
Any first-party payload that identifies a tracked mission must carry the canonical identity fields:
| Field | Required | Meaning |
|---|---|---|
mission_id | Yes | Canonical ULID machine identity (e.g. 01J6XW9KQT7M0YB3N4R5CQZ2EX). Aggregate routing uses this field. |
mission_slug | Yes | Human-readable mission slug (e.g. my-feature). Display context only. |
mission_number | Yes, nullable | Display-only numeric prefix (e.g. 77). null pre-merge, assigned at merge time. Never used for identity. |
mission_type | Yes | Blueprint key (for example software-dev). |
Forbidden mission-scoped payload fields:
feature_slugfeature_numberfeature_type
This applies to first-party machine-facing payloads such as status snapshots,
derived board/progress views, context tokens, acceptance matrices, merge-gate
evaluations, next --json decisions, and orchestrator-api response payloads.
Body Sync Payloads
The body_sync contract requires:
| Field | Required |
|---|---|
project_uuid | Yes |
mission_slug | Yes |
target_branch | Yes |
mission_type | Yes |
manifest_version | Yes |
Forbidden body-sync fields:
feature_slugmission_key
Compatibility Notes
- Historical read paths may still accept
feature_slugwhen ingesting old artifacts such as legacystatus.events.jsonlrecords. - Active first-party emitters must not dual-write
feature_slug. mission_run_slugis forbidden.- Catalog event names remain
MissionCreatedandMissionClosed. aggregate_type="MissionRun"is forbidden.
Migration
Operator-facing CLI migration guidance lives here:
The migration policy is asymmetric:
- human/operator CLI surfaces may still accept hidden deprecated aliases during the migration window
- machine-facing contracts are canonical-only on
mission_*