---
id: spec-kitty-events
version: "6.1.0"
license: MIT License Copyright (c) 2026 Spec Kitty Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# spec-kitty-events — Event log library with Lamport clocks and systematic error tracking

License: permissive · Maintenance: active · Downloads: 139.0K/mo

## 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 above — 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

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

- License: MIT License Copyright (c) 2026 Spec Kitty Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 139.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

event envelope contracts, mission state events, lamport clock events, event validation schema, canonical event log, conformance validation, event schema contracts, event-sourcing, schema-contracts, distributed-tracing

[View on SkillFed](https://skillfed.io/packages/spec-kitty-events) · [View on PyPI](https://pypi.org/project/spec-kitty-events/)