job_complete

Category: jobs_lanes
Access: write
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Completes a claimed job as completed or failed. Call it when execution of one Job unit has finished and its outcome plus result reference must become durable.

Arguments

Required: job_id, outcome.

Optional: result_ref.

job_id.
outcome. Note: completed or failed only.
result_ref. Note: Optional pointer at the produced artifact or verdict; kept as an opaque reference.

Result

JSON object with job_id and state (completed or failed). Idempotent replays add idempotent:true.

Boundaries

Owner path needs a live lease held by the caller; the conductor path may complete any claimed entry and skips the lease check. Out-of-scope entries read as missing with job not found vocabulary, so callers cannot probe foreign projects. Operates only inside the caller's profile boundary.

Lifecycle / side effects

Moves a claimed entry to completed or failed and records an audit/history event. Re-completing with the same outcome succeeds without change and without a further event (idempotent:true in that answer). Association with a lane never moves the claim gate. The delivery pump writes only job delivery, lease, and result facts, never lane decision or review standing.

Errors

job not found covers missing and out-of-scope identically. job is not claimed covers wrong standing. lease expired tells an owner to reclaim first. Re-completing a terminal entry with a different outcome is rejected as job already terminal. Bad outcome values are rejected.

Example

{
  "job_id": "<uuid>",
  "outcome": "completed",
  "result_ref": "verdict:<uuid>"
}

Result shape:

{
  "job_id": "<uuid>",
  "state": "completed"
}