spec-kitty-events

What it is and what it does

spec-kitty-events is a Python event contract library that defines canonical envelope schemas for mission state, runtime, and conformance events. It enforces a fail-closed cutover policy where live ingestion rejects legacy mission-domain field names (like `feature_slug`, `mission_key`) and requires modern canonical fields (`mission_slug`, `mission_number`, `mission_type`) plus envelope metadata (`build_id`, `node_id`, `schema_version="3.0.0"`). The package uses Pydantic models for validation and includes Lamport clock support for distributed event ordering.

The library serves teams migrating from legacy event shapes to canonical 3.x contracts. It provides conformance validation combining Pydantic validation, committed JSON Schemas, and cutover artifact checks. A legacy normalizer can promote known pre-cutover envelope shapes to canonical form with deterministic UUID5 minting and audit preservation, while surfacing un-normalizable rows as structured diagnostics rather than silent passes. The package also exports `LOCAL_ONLY_EVENT_TYPES` for downstream consumers to identify event types not routed through SaaS-bound producer paths.

Use it for:

• Emit and validate canonical event envelopes with build/node identity and Lamport clock ordering in mission tracking systems
• Validate incoming event payloads against canonical contracts to enforce fail-closed cutover policy during TeamSpace migration
• Normalize legacy pre-3.0 event shapes to canonical form with audit trail preservation and deterministic UUID generation
• Run conformance gates combining Pydantic validation, JSON Schema drift checks, and cutover artifact verification in CI/CD
• Classify event types for routing decisions (e.g., identify events that do not cross SaaS boundaries)

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides canonical event envelope contracts and validation for Spec Kitty mission state, runtime, and conformance tracking, with Lamport clock support and fail-closed cutover semantics.

Yes. The package is actively maintained, has low install friction, carries no known vulnerabilities, and is MIT-licensed. Install it if you are building or migrating to a Spec Kitty event system that requires canonical envelope contracts with fail-closed cutover semantics and legacy shape normalization. The conformance validation and Lamport clock support are production-grade for mission state tracking.

Install

spec-kitty-events on PyPI

pip install spec-kitty-events

uv add spec-kitty-events

poetry add spec-kitty-events

Installing spec-kitty-events

Before you install

Low friction: pure Python wheel with only pydantic and python-ulid as runtime dependencies. Active maintenance with latest release 61 days ago.

License in practice

MIT License permits unrestricted use, modification, and distribution with only copyright notice and license text preservation required.

Quickstart

pip install spec-kitty-events

from spec_kitty_events import Event
from datetime import datetime
import uuid

event = Event(
    event_id="01ARZ3NDEKTSV4RRFFQ69G5FAV",
    event_type="WPStatusChanged",
    aggregate_id="mission/WP01",
    payload={"mission_slug": "mission-001"},
    timestamp=datetime.now(),
    build_id="build-001",
    node_id="runner-01",
    lamport_clock=1,
    project_uuid=uuid.uuid4(),
    correlation_id="01ARZ3NDEKTSV4RRFFQ69G5FAV",
    schema_version="3.0.0"
)

Requires Python >=3.10

Verify before relying

• Whether conformance validation fixtures for TeamSpace migration are production-ready or development-only
• Performance characteristics under high-volume event emission
• Whether legacy_envelope_v1 normalization covers all known pre-cutover shapes in production use

Package facts

Evidence: spec_kitty_events-6.1.0-py3-none-any.whl

Tags

More Software Development packages