[Consumer] Harden the status.json consumer example: pointer fix, poll dedup, and an interactive dry-run

[HereThereBeDragons]

Summary

Upstreams the findings from ROCm/rocm-examples#505 into Quartz's own
status.json consumer docs and helper, and hardens the example against the
failure modes a real downstream poller hits.

The core bug: latest.json and prerelease/latest.json are git symlinks, and
raw.githubusercontent.com serves a symlink as its target path (a one-line
body like 20260707/status.json), not the file it points to. A plain fetch of
latest.json therefore returns that path, and parsing it as JSON fails. This
broke the most obvious way to consume the "latest" endpoint.

Read helper (scripts/consumer/read_status_json.py)

• load_status now follows the symlink pointer transparently: on a JSON decode
  failure it checks whether the body is a bare <date>/status.json pointer,
  resolves it against the source URL with urljoin, and fetches the real
  document once. Anything that is not clearly a pointer re-raises the original
  error, so genuine malformed JSON still surfaces. Local paths follow symlinks
  natively and never take this fallback.
• Added read_status_json_test.py covering the pointer-resolution path.

Poll workflow and consumer example (the larger change)

The workflow side is where most of the work went, because a naive poller either
re-triggers on every poll or double-processes a build:

• Deduplication via actions/cache keyed on (rocm_version, build_date).
  restore is lookup-only (no download) and only probes; the marker is saved
  only after the React step succeeds, so a failed run is retried on the next
  poll rather than being marked done.
• Concurrency: a static concurrency group serializes overlapping polls and
  lets an in-flight run finish. This is what makes a single save-after marker
  sufficient even when the work outlives the poll interval: React always writes
  its marker before the next poll starts.
• Fire-and-forget caveat: a concurrency group only serializes runs of the
  same workflow. If the poll dispatches a separate long-running workflow, that
  run is independent and the poll's serialization does not extend to it. The
  tutorial documents the fix (move the marker into the dispatched workflow, key
  its own concurrency per build) with a worked my_build.yml sample.

The Python example (example_consume_status.py) was also hardened:

• A transient fetch failure (status.json momentarily unavailable around a
  release) reports ready=false and exits 0 so the next poll retries.
• An unsupported schema major is treated as permanent and fails loudly
  (sys.exit, non-zero): retrying cannot fix it, and a new major can move the
  fields the accessors read, so continuing would risk silently misreading the
  document.
• The pip dry-run step now echoes the command and streams pip's output live, so
  the wait is visible, and targets a smaller device package (device-gfx1150)
  to keep the example quick.
• Added example_consume_status_test.py (9 tests) covering the gate, the
  outputs glue, and the ready / not-ready / schema-fail branches.

Docs

• README documents the latest.json pointer behavior and how to resolve it by
  hand if you fetch it yourself.
• tutorial.md gains the "Dispatching a separate long-running workflow" section
  and the per-workflow marker guidance.

Test plan

• python3 -m unittest discover -s docs/status-json/tests -p '*_test.py'
• python3 -m unittest discover -s scripts/consumer/tests -p '*_test.py'
• python3 docs/status-json/example_consume_status.py against the live
  latest.json endpoint (confirms the pointer fix end to end)

[marbre]

Is this block needed or rather, can we link / inline the example_poll_status.yml to not duplicate?

[HereThereBeDragons]

shortened it. its not identical. it talks about how in workflow dispatch workflows you need another cache marker/concurrency group (thanks also found the bug where i missed to change the concurrency group name)

[zichguan-amd]

Thanks for upstreaming this in Quartz, LGTM

[cgoea]

concurrency:
queue: max

should be better according to https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency#using-concurrency-in-different-scenarios . If a long-running poll is active, a manual forced run is pending, and the next scheduled poll arrives, GitHub cancels the pending forced run and replaces it from what I can tell. Also maybe use "group: ${{ github.workflow }}-poll-rocm-nightly" to avoid collisions ...

[HereThereBeDragons]

ah down the rabbit hole :)

To conditionally cancel currently running jobs or workflows in the same concurrency group, you can specify cancel-in-progress as an expression with any of the allowed expression contexts.

how about instead

cancel-in-progress: ${{ inputs.force }}

so that the queue is the normal "last request to rerun" and if you want a manual forced run it cancels the ongoing one?

can add the link to the concurrency page for workflows: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#concurrency
for people to discover more

---

leaving it as an exercise for the downstream user:
you can extend this even further of creating totally separate groups depending if scheduled or not. needs to be then propagated to workflow dispatch though.

concurrency:
  group: poll-rocm-nightly-${{ inputs.force == true && 'manual' || 'scheduled' }}
  cancel-in-progress: ${{ inputs.force }}

[HereThereBeDragons]

thinking about it a bit more:
i think for this example it is better to remove the input for force overwrite.
if anyone wants it they can come up with it and its implications themselves

[HereThereBeDragons]

Also maybe use "group: ${{ github.workflow }}-poll-rocm-nightly" to avoid collisions ...

i would leave as-is to stay minimal. we have a section in the tutorial about concurrency groups. people can have a look there. if you start with concurrency groups you should know at least a little bit about it...