Skip to content

Crafting / Core / Lifecycle

Purpose

This folder defines the canonical lifecycle vocabulary used by the Crafting system.

Types in Lifecycle describe what phase a crafting job is in — not how that phase is executed and not what caused it.

This vocabulary is shared across: - runtime job execution - event streams - UI feedback - Teachables and diagnostics

By centralising lifecycle terms, the system avoids duplicated enums, ambiguous states, and mismatched interpretations.

What lives here

JobLifecyclePhase

  • JobLifecyclePhase
  • Unified, high-level lifecycle phases emitted by the crafting service.
  • Used by CraftingServiceCore.OnJobLifecycle and related events.

Phases are intentionally coarse-grained:

  • Enqueued – job created and accepted (inputs/currency already consumed)
  • Started – job entered running state
  • Progress – progress notification (throttled)
  • Completed – outputs delivered successfully
  • Cancelled – job cancelled by caller
  • Failed – job failed with an explicit reason

These phases are designed for observation, not control.

Relationship to job state

JobLifecyclePhase is not the same as CraftJobState.

  • CraftJobState is a runtime state machine used internally by the service.
  • JobLifecyclePhase is a public notification vocabulary.

A single CraftJobState may emit multiple lifecycle phases over time (e.g. multiple Progress phases while Running).

Callers must not infer internal state transitions from lifecycle events.

What does NOT belong here

  • Job scheduling logic
  • Failure reasons
  • Timing or progress calculations
  • State machines or transitions
  • Control APIs

This folder defines language, not behaviour.

Usage rules

For event consumers

  • Treat lifecycle events as notifications, not commands.
  • Do not assume delivery order beyond what is documented or implied by a single job’s execution.
  • Always pair lifecycle phases with CraftFailReason when handling failures.

For UI and analytics

  • Use lifecycle phases to drive UI, telemetry, and logging.
  • Do not attempt to reconstruct internal job state from events alone.
  • Use job queries (GetJobs, GetJobsByState) for authoritative state.

Public API guarantee

All types in this folder are part of the supported public API.

  • New lifecycle phases may be added in future versions.
  • Existing phases will not change meaning.
  • Removal or semantic changes require a major version bump.

Teachables depend on this vocabulary to remain stable across releases.

Design notes

  • Lifecycle phases are deliberately simple.
  • They describe what happened, not why or how.
  • This separation keeps events stable even when internals evolve.

If you need more detail than a lifecycle phase provides, listen to additional events or query the service directly.