Runtimes

A runtime is mutable state used while authoring a DAG or tracking execution. Finalizing it creates an immutable DAG. Use the CLI to inspect and administer open work; use named committed DAGs for completed research.

Freeze and resume authoring

runtime_ref="$(dml runtime create)"
printf '["scalar",42]\n' | dml runtime put-literal "$runtime_ref" - --name answer >/dev/null
frozen_ref="$(dml runtime freeze "$runtime_ref" --message "Review staged input")"

dml runtime list | jq -e --arg frozen "$frozen_ref" '.[] | select(.id == $frozen)'
dml runtime describe "$frozen_ref" | jq -e '.state == "frozen" and .frozen_message == "Review staged input"'
answer_ref="$(dml runtime get-node "$frozen_ref" answer)"
dml dag get-node "$answer_ref" | jq -e '.[1] == 42'

resumed_ref="$(dml runtime unfreeze "$frozen_ref")"
dml runtime freeze "$resumed_ref" --message "Leave the demonstration read-only" >/dev/null

{
  "author": "runner@runnervmlun5p",
  "created": "2026-09-20T03:16:24.076597+00:00",
  "dag": "dag:fddaecd49ea1cbf67fd367bdb95372f57c42aaed9439a5b009d28c598331470e",
  "frozen_message": "Review staged input",
  "id": "frozenindex:01a0bcd09f407d419de53f52e61ae14c",
  "message": "",
  "parents": [
    "commit:fc7a06c812242ee14b34b2506076d86e9900ce0cfb6947c7d0ec0403549304bb"
  ],
  "state": "frozen",
  "tree": "tree:6f8c189d61ebe6397698380f823751d36b5926f7b197a386aea6935bba6db8c9"
}
true
true

Freezing preserves partial nodes, tags, and execution identity, but does not create a result. Its message is a reason, not a durable name. Dag.freeze() and Dag.unfreeze() manage the normal Python wrapper; dml.resume(frozen, name=..., message=...) resumes it in another process. Runtime and execution identities are complete Ref values (index: or frozenindex:), never bare IDs.

Inspect, cancel, and refresh deliberately

runtime describe, describe-graph, and read-execution-record report graph, lifecycle, lineage, cancellation, invalidation, adapter continuation, shared retry deadlines, and cleanup. Cleanup may remain pending or fail without making an otherwise reusable result unavailable.

course_ref="$(dml show | jq -er '.dags["course-execution"]')"
first_ref="$(dml dag get-node-by-name "$course_ref" script-first)"
execution_dag_ref="$(dml dag describe-node "$first_ref" | jq -er '.dag')"
cache_key="$(dml dag describe "$execution_dag_ref" | jq -er '.cache_key')"
cache_description="$(dml cache describe "$cache_key")"
execution_ref="$(jq -er '.execution' <<< "$cache_description")"

jq -e --arg dag "$execution_dag_ref" '.dag == $dag and .lifecycle == "succeeded"' <<< "$cache_description"
printf '%s\n' "$execution_ref" > "$DOCS_WORKSPACE_ROOT/invalidated-course-execution"
dml cache invalidate "$execution_ref"

true
{"invalidations":[{"cache_key":"fe612bf7a9a547ba609acb7d75c197744abb456e6b0d46725e8d8c4aeec2ad8e","execution_id":"01a0bcd06087784f972d19943a9390e9","requested_at":1789874189,"requested_by":"runner@runnervmlun5p"}],"total_time":0.13478422164916992}

Rerunning the same stored runnable and argument produces a new execution for the same normalized cache key:

import daggerml as dml

course = dml.load("course-execution")
with dml.new("course-refresh", message="refresh invalidated course work") as dag:
    runnable = dag.put(course["script"], name="script")
    source = dag.put(course["source"], name="source")
    refreshed = runnable(source, name="refreshed")
    dag.commit(refreshed)

assert dml.load("course-refresh").result.value() == {"count": 3, "total": 10}

refreshed_ref="$(dml show | jq -er '.dags["course-refresh"]')"
refreshed_result="$(dml dag get-node-by-name "$refreshed_ref" refreshed)"
refreshed_dag="$(dml dag describe-node "$refreshed_result" | jq -er '.dag')"
refreshed_key="$(dml dag describe "$refreshed_dag" | jq -er '.cache_key')"
new_execution="$(dml cache describe "$refreshed_key" | jq -er '.execution')"
old_execution="$(cat "$DOCS_WORKSPACE_ROOT/invalidated-course-execution")"
test "$new_execution" != "$old_execution"

Invalidate exact execution refs, not cache keys or DAG refs. This affects every caller sharing remote.root, so inspect the returned identity and coordinate before refreshing work. Cancellation first selects the complete unreferenced set as cancel-pending, conditionally removes matching cache pointers, then cancels adapters concurrently. Retry responses share not_before; repeated dml runtime cancel index:... --max-retries 3 resumes pending cancellation. An execution that already finished is a successful no-op. Continue with Sharing; cache invalidation is deliberately last among workflows that need the original cached result.