Deployments and runs

Magmell separates preparing code from invoking it. That separation keeps normal runs fast and makes the executed artifact explicit.

Deployment lifecycle

create
  │
  ▼
building ─────────────► build_failed
  │
  ▼
ready ────────────────► archived

• building: source and requirements are being assembled into a runtime artifact.
• ready: the artifact can accept runs.
• build_failed: the artifact was not produced; inspect build logs.
• archived: the deployment was deleted and no longer participates in active name resolution.

Deployments are team-scoped. The handler name and version are unique among active deployments in that team.

Run lifecycle

queued ──► running ──► succeeded
   │          │
   │          └──────► failed
   └─────────────────► failed (queue timeout)

Creating a run is intentionally quick: the gateway validates it, stores it as queued, and returns an identifier. A dispatcher claims queued work subject to team and platform concurrency limits.

While running, Magmell renews an execution lease. Reconciliation handles interrupted infrastructure so work does not remain permanently stuck in a non-terminal state.

IDs, names, versions, and numbers

Value	Scope	Use
Deployment ID	Global	Exact immutable build
Handler name	Team	Human-facing family of versions
Version	Handler name	Select a particular release
Run ID	Global	Exact invocation
Run number	Handler name	Short human reference across versions

Use deployment IDs when exactness matters inside automation. Use a handler name plus optional version for readable application code. Use name#number in support conversations and operational work.

Queueing and concurrency

Runs may remain queued while the team is at its concurrency limit. A full per-team queue returns HTTP 429 instead of accepting unbounded work. Runs that exceed the configured maximum queue age fail with a queue-timeout error.

Results are durable records

Polling the run record is the canonical way to determine its outcome. Webhooks are a notification mechanism, not an alternative source of truth. A successful run stores result; a failed run stores a redacted error. Both retain their event timeline.