Skip to content

Context: System Events

Who is this for (2)

Context: System Events

Terms describing Spec Kitty’s append-only event model, replay behavior, and system-level event types.

Event Envelope

DefinitionStandard wrapper for an emitted event, including identity, ordering, and payload fields.
ContextSystem Events
Statuscanonical
Applicable to1.x, 2.x
Common fieldsevent_id, event_type, aggregate_id, lamport_clock (optional), payload (the Event model in spec_kitty_events.models)

Glossary Evolution Log

DefinitionAppend-only sequence of glossary-related events that records candidate extraction, semantic checks, clarifications, and sense updates. Stored per Mission in .kittify/events/glossary/<mission_id>.events.jsonl (src/glossary/events.py).
ContextSystem Events
Statuscanonical
Applicable to1.x, 2.x
Related termsSemantic Check, Clarification Prompt

Glossary Scope

DefinitionBounded semantic scope used for term/sense resolution.
ContextSystem Events
Statuscanonical
Applicable to1.x, 2.x
Allowed valuesspec_kitty_core, team_domain, audience_domain, mission_local (GlossaryScope in src/glossary/scope.py)

Semantic Check Evaluation

DefinitionDeterministic pre-generation evaluation of extracted terms against active glossary scopes.
ContextSystem Events
Statuscanonical
Applicable to1.x, 2.x
Block ruleDepends on the glossary strictness (src/glossary/strictness.py): off never blocks, medium blocks on an unresolved high-severity conflict, max blocks on any unresolved conflict

Replay

DefinitionReconstructing effective glossary state and decisions from canonical append-only events.
ContextSystem Events
Statuscanonical
Applicable to1.x, 2.x
InvariantNo side-channel state may be required for correctness

Telemetry (Out of Scope for This Slice)

DefinitionOptional usage/cost analytics and operational observability fields layered on top of core event contracts.
ContextSystem Events
Statuscandidate
Applicable to1.x, 2.x
NoteNot required for glossary semantic integrity in this 2.x adoption slice

Dossier Event

DefinitionAn event emitted during dossier operations. Four types: MissionDossierArtifactIndexed (artifact scanned), MissionDossierSnapshotComputed (snapshot created), MissionDossierArtifactMissing (required artifact not found), MissionDossierParityDriftDetected (content changed since baseline).
NoteThe four emitters in src/specify_cli/dossier/events.py are defined, but no code path in src/ calls them today.
ContextSystem Events
Statuscandidate
Applicable to1.x, 2.x
Related termsMission Dossier, Anomaly Event, Event Envelope

Anomaly Event

DefinitionAn event that is only emitted when something unexpected happens — such as a required artifact being missing or parity drift being detected. Unlike routine lifecycle events, anomaly events signal conditions that may need the Human-in-Charge’s attention.
NoteThe dossier anomaly events (MissionDossierArtifactMissing, MissionDossierParityDriftDetected) are not emitted by any code path in src/ today; see Dossier Event.
ContextSystem Events
Statuscandidate
Applicable to1.x, 2.x
Related termsDossier Event, Human-in-Charge (HiC)

WPStatusChanged

DefinitionThe event type that carries a work package’s move from one status lane to another (e.g., from planned to claimed). Part of the status model’s event contract: the CLI writes each move as a StatusEvent row in status.events.jsonl, and build_status_event_payload (src/specify_cli/status/wire_payload.py) renders that row as a WPStatusChanged payload.
ContextSystem Events
Statuscanonical
Applicable to1.x, 2.x
Related termswork package, Lane, Event Envelope

Lamport Clock

DefinitionA logical counter included in event envelopes that tracks the order events happened in, without relying on wall-clock time. Each new event increments the counter, ensuring events can be reliably ordered even across different machines.
NoteThe field is optional in the envelope. The CLI’s status lane transitions carry no Lamport clock, and the status reducer orders them by the writer’s at timestamp, then event_id (ADR 2026-02-09-3, Amendment 2026-10-22). Do not describe the status path as Lamport-ordered.
ContextSystem Events
Statuscanonical
Applicable to1.x, 2.x
Related termsEvent Envelope, Replay

Tail cursor

DefinitionThe reader’s resumable position in spec-kitty events tail — a byte offset into the selected log of a named Mission (status.events.jsonl by default; --log selects decisions, mission, run, glossary, ops or canonical), plus a content invariant (a fixed-size SHA-256 hex digest of the last-consumed line/boundary bytes at that offset, never the raw bytes themselves) used to re-verify on every poll that growth at that offset is a true continuation and not a rollback-then-regrow landing back at or above the same size. Always caller-supplied/caller-owned: events tail is stateless across invocations and never persists cursor or resume state to disk anywhere.
ContextSystem Events
Statuscandidate
Applicable to3.x
Distinct fromEvent Envelope — a Tail cursor is reader-side position/verification state (offset + content-invariant digest), never a wrapper around an emitted event’s own identity/ordering/payload fields (event_id/event_type/aggregate_id/lamport_clock/payload).
Related termsTail envelope, resume token

resume token

DefinitionThe (offset, content_invariant) pair a consumer of spec-kitty events tail persists across restarts and supplies back via --from-offset/--from-invariant, so a cold-started process can resume where a prior run left off. Persisting the offset alone (with no invariant) only enables structural resume validation; supplying both enables FR-013’s cross-restart content-mismatch check, which refuses the resume (structured stderr error, non-zero exit, no Tail envelope emitted) rather than silently trusting a stale or rolled-back-then-regrown position.
ContextSystem Events
Statuscandidate
Applicable to3.x
Distinct fromEvent Envelope — a resume token is the consumer’s own persisted (offset, content_invariant) value, never an emitted event’s event_id/lamport_clock-shaped wrapper; also distinct from Tail cursor, which is the reader’s own live in-memory position — a resume token is what a consumer chooses to durably persist FROM a Tail cursor’s offset/invariant, across process restarts, never automatically.
Related termsTail cursor, Tail envelope

log_truncated

DefinitionThe Tail envelope stream’s truncation-resync signal shape, emitted when spec-kitty events tail detects a rollback (a size shrink, or a truncate-then-regrow whose content invariant no longer matches at the previously-consumed offset) while running. Carries a "type": "log_truncated" discriminator (absent from ordinary pass-through rows), a reason of "size_shrink" or "content_mismatch", the detected_at_offset, and a resync tail_offset/tail_invariant pair at offset 0 — never silently absorbed as “no new data.”
ContextSystem Events
Statuscandidate
Applicable to3.x
Distinct fromEvent Envelope — log_truncated is one of the Tail envelope stream’s own signal shapes, never a StatusEvent/canonical-Event-Envelope row; its "type" discriminator is exactly what lets a consumer tell the two apart on the same stream.
Related termsTail envelope, Tail cursor

Tail envelope

DefinitionOne JSON line emitted on stdout by spec-kitty events tail in --json mode (#6611) — either a pass-through of an existing line of the selected log (for the default status log, a StatusEvent dict as already serialized by store.py), or one of the two new signal shapes this command defines: the log_truncated truncation-resync signal (FR-005/FR-007) and a resolve-failure/error signal (FR-009), the latter emitted on stderr only, never on the stdout Tail-envelope stream itself. Every pass-through envelope also carries the offset and content-invariant value immediately past the emitted event, so a consumer can persist both (as a resume token) without deriving them itself. Without --json the command prints one human-readable plain-text line per event instead (the reader-injected cursor keys omitted); the Tail envelope is the machine channel.
ContextSystem Events
Statuscandidate
Applicable to3.x
Distinct fromEvent Envelope — the canonical Event Envelope term names a differently-shaped wrapper (event_id/event_type/aggregate_id/lamport_clock/payload); a Tail envelope here is always either a raw line of the selected log (a StatusEvent JSON line for the status log) or one of events tail’s own signal shapes, never that canonical schema.
Related termsTail cursor, resume token, log_truncated