Skip to content

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 Type is the reusable blueprint key, serialized as mission_type.
  • Mission is the tracked item under kitty-specs/<mission-slug>/. Its canonical machine identity is mission_id (a ULID). The human-readable mission_slug and the display-only mission_number are serialized alongside it for context, but selectors and event routing use mission_id.
  • Mission Run is 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:

FieldRequiredNotes
schema_versionYesMust equal 3.0.0.
build_idYesProducer build identifier.
aggregate_typeYesAllowed: Mission, WorkPackage, MissionDossier. Forbidden: Feature.
event_typeYesEvent name for the emitted record.

Forbidden top-level fields in the envelope:

  • feature_slug
  • feature_number

Mission-Scoped Payloads

Any first-party payload that identifies a tracked mission must carry the canonical identity fields:

FieldRequiredMeaning
mission_idYesCanonical ULID machine identity (e.g. 01J6XW9KQT7M0YB3N4R5CQZ2EX). Aggregate routing uses this field.
mission_slugYesHuman-readable mission slug (e.g. my-feature). Display context only.
mission_numberYes, nullableDisplay-only numeric prefix (e.g. 77). null pre-merge, assigned at merge time. Never used for identity.
mission_typeYesBlueprint key (for example software-dev).

Forbidden mission-scoped payload fields:

  • feature_slug
  • feature_number
  • feature_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:

FieldRequired
project_uuidYes
mission_slugYes
target_branchYes
mission_typeYes
manifest_versionYes

Forbidden body-sync fields:

  • feature_slug
  • mission_key

Compatibility Notes

  • Historical read paths may still accept feature_slug when ingesting old artifacts such as legacy status.events.jsonl records.
  • Active first-party emitters must not dual-write feature_slug.
  • mission_run_slug is forbidden.
  • Catalog event names remain MissionCreated and MissionClosed.
  • 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_*