From aedc49f61e3bc77de3d688f2e2a91bad37d08ddb Mon Sep 17 00:00:00 2001
From: Arjun Raj <arjunrajlab@gmail.com>
Date: Sat, 30 May 2026 15:00:07 -0400
Subject: [PATCH 1/7] docs: spec for strict out-of-range coordinate validation
 in WorkerClient

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...t-of-range-coordinate-validation-design.md | 204 ++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-30-out-of-range-coordinate-validation-design.md

diff --git a/docs/superpowers/specs/2026-05-30-out-of-range-coordinate-validation-design.md b/docs/superpowers/specs/2026-05-30-out-of-range-coordinate-validation-design.md
new file mode 100644
index 0000000..90b53cb
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-30-out-of-range-coordinate-validation-design.md
@@ -0,0 +1,204 @@
+# Out-of-range coordinate validation in the WorkerClient path
+
+**Date:** 2026-05-30
+**Status:** Design — pending implementation
+
+## Problem
+
+When a user enters a `Batch XY`, `Batch Z`, or `Batch Time` range that includes
+coordinates not present in the dataset, annotation workers crash with a raw
+`KeyError` and a full stack trace instead of a useful, actionable message.
+
+Reproduction (reported): running Cellpose-SAM with `Batch XY: "80-90"` on a
+dataset that has only one XY position. The parser converts the 1-indexed
+`80-90` to 0-indexed `79-89`; the worker then crashes at:
+
+```
+File ".../annotation_client/tiles.py", line 134, in coordinatesToFrameIndex
+    return self.map[channel][T][Z][XY]
+KeyError: 79
+```
+
+### Crash path
+
+`WorkerClient.process()` parses `Batch XY/Z/Time` into ranges, then loops:
+`process()` → `get_image_stack()` → `get_image()` → `coordinatesToFrameIndex()`,
+which does `self.map[channel][T][Z][XY]` and raises a bare `KeyError` the moment
+a coordinate is missing. No `sendError`, so the user sees only a stack trace.
+
+### Scope of affected code (from a full sweep)
+
+- **6 workers go through the shared `WorkerClient.process()` path** — cellposesam,
+  cellpose, condensatenet, laplacian_of_gaussian, random_squares,
+  sample_interface. A single central fix covers all of them.
+- **~26 other workers** iterate batch ranges or call `coordinatesToFrameIndex()`
+  directly (SAM2 family, cellori, registration, crop, histogram_matching,
+  cellpose_train, etc.). These are **out of scope** for this change; the shared
+  validator added here is written so they can adopt it later.
+
+Existing in-repo validation patterns this design follows: `blob_intensity_worker`,
+`crop`, and `registration` build `range_x = range(0, IndexRange['IndexXY'])`,
+filter/validate coordinates, and report in 1-indexed terms.
+
+## Decisions
+
+- **Behavior:** *Strict* — if **any** requested coordinate is out of range,
+  `sendError` with the valid range and stop before doing work. (Not the
+  filter-and-warn-subset approach used by some property workers.)
+- **Scope:** Central `WorkerClient.process()` path first. Other workers deferred.
+- **No cross-repo changes:** The shared `annotation_client/tiles.py`
+  (`coordinatesToFrameIndex`) in the NimbusImage repo keeps its bare `KeyError`
+  as a last-resort backstop. A separate GitHub issue is filed there to harden it
+  later.
+- **Fail before expensive work:** Cellpose-SAM loads its GPU model in
+  `compute()` *before* `worker.process()` runs. To fail instantly (before the
+  ~5-10s model load), `cellposesam.compute()` calls the validator early.
+
+## Design
+
+### 1. Pure validator — `annotation_utilities`
+
+New module `annotation_utilities/annotation_utilities/coordinate_validation.py`.
+Pure functions, no `sendError` side effects (keeps them unit-testable and
+reusable by the deferred workers):
+
+```python
+def find_out_of_range(index_range, xys=None, zs=None, times=None):
+    """Return {dim: (sorted_bad_0indexed_values, dim_size)} for any requested
+    coordinate < 0 or >= the dimension's size. Empty dict means all valid.
+
+    `dim` is one of 'XY', 'Z', 'Time'. A missing IndexRange, or a missing
+    IndexXY/IndexZ/IndexT sub-key, defaults that dimension's size to 1 —
+    matching the existing fallback convention (blob_intensity, get_image_stack).
+    Dimensions passed as None are skipped."""
+
+def format_out_of_range_message(invalid):
+    """Build a single (message, info) pair for sendError. XY/Z/Time values are
+    reported 1-INDEXED to match what the user typed in the 'Batch XY/Z/Time' UI
+    fields (the batch parser converts 1->0 on input). Contiguous runs collapse
+    to 'a-b'; otherwise a comma-separated list."""
+```
+
+Example output for the reported bug:
+
+> **message:** `"Batch XY is out of range"`
+> **info:** `"You requested XY position(s) 81-91, but this dataset has only 1 XY position (valid: 1). Please adjust the 'Batch XY' field."`
+
+`dim` → UI label mapping for messages: `XY` → "Batch XY", `Z` → "Batch Z",
+`Time` → "Batch Time".
+
+### 2. `WorkerClient` changes — `worker_client/worker_client/worker_client.py`
+
+**a. Materialize batch ranges to lists in `__init__`.** `process_range_list`
+returns a generator; storing it as a generator means it can only be consumed
+once. Since both `validate_coordinates()` and `process()` now read these, store
+them as lists:
+
+```python
+self.batch_xy = list(batch_xy)
+self.batch_z = list(batch_z)
+self.batch_time = list(batch_time)
+```
+
+(`batch_xy` is either a generator from the parser or a `[tile['XY']]` fallback;
+`list(...)` is correct for both. No current caller depends on them being lazy.)
+
+**b. New public method `validate_coordinates()`** (single source of truth):
+
+```python
+def validate_coordinates(self, stack_xys=None, stack_zs=None, stack_times=None):
+    """Strictly validate the batch coordinates that will be iterated against
+    the dataset's IndexRange. If any requested XY/Z/Time coordinate is out of
+    range, sendError with an actionable message and raise ValueError.
+
+    Safe to call early (e.g. before loading an expensive model); also called
+    internally by process(). Idempotent and side-effect-free unless a
+    coordinate is out of range."""
+    xys   = list(self.batch_xy)   if stack_xys   is None else [self.tile['XY']]
+    zs    = list(self.batch_z)    if stack_zs    is None else [self.tile['Z']]
+    times = list(self.batch_time) if stack_times is None else [self.tile['Time']]
+
+    index_range = self.datasetClient.tiles.get('IndexRange', {})
+    invalid = coordinate_validation.find_out_of_range(
+        index_range, xys=xys, zs=zs, times=times)
+    if invalid:
+        message, info = coordinate_validation.format_out_of_range_message(invalid)
+        sendError(message, info=info)
+        raise ValueError(message)
+```
+
+The `stack_*` arguments mirror `process()`: for a dimension the worker *stacks*
+(not batches), the effective coordinate is the current tile (`self.tile[...]`),
+which is valid by construction and passes harmlessly; for a *batched* dimension
+it is the user's range — exactly what we want to check.
+
+**c. Call it at the top of `process()`**, before the loop:
+
+```python
+self.validate_coordinates(stack_xys, stack_zs, stack_times)
+```
+
+**d. Import `sendError`** by extending the existing
+`from annotation_client.utils import sendProgress` line, and import the new
+`coordinate_validation` module from `annotation_utilities`.
+
+Channels are intentionally **not** validated here: `channelCheckboxes` can only
+select channels that already exist, so they cannot produce this bug, and mixing
+0-indexed channel messaging with 1-indexed XY/Z/Time messaging would confuse the
+error. The validator is structured so channel validation can be added later.
+
+### 3. Early check in Cellpose-SAM — `workers/annotations/cellposesam/entrypoint.py`
+
+Add one line near the top of `compute()`, right after the `WorkerClient` is
+constructed and **before** the model is downloaded/loaded:
+
+```python
+worker = WorkerClient(datasetId, apiUrl, token, params)
+worker.validate_coordinates()   # fail fast before loading the GPU model
+```
+
+Cellpose-SAM batches XY/Z/Time and stacks channels, so the default
+(no-`stack_*`) validation of `batch_xy/z/time` is exactly correct. `process()`
+re-validates internally; the duplicate call is cheap and idempotent.
+
+## Testing
+
+Follow the existing `*_index_range.py` pattern (a `DummyDatasetClient` with a
+`.tiles` dict; `annotation_client` submodules mocked).
+
+- **`annotation_utilities/tests/test_coordinate_validation.py`** — pure-function
+  tests:
+  - all in-range → empty dict / no message
+  - out-of-range detected per dimension, with correct size
+  - missing `IndexRange` ⇒ dimension size defaults to 1 (only coord 0 valid)
+  - missing single sub-key (e.g. `IndexZ`) ⇒ that dim defaults to 1
+  - message is 1-indexed and names the right `Batch *` field
+  - multiple offending dimensions reported together
+  - contiguous-run collapsing (`81-91`) vs. comma list
+
+- **`worker_client/tests/test_worker_client_index_range.py`** (extend) — add a
+  module-level recorder for a monkeypatched `utils.sendError`, then:
+  - `IndexRange={'IndexXY':1}`, `workerInterface={'Batch XY':'80-90'}` →
+    `process()` calls `sendError` once and raises `ValueError`; the processing
+    loop never runs (no `getRegion` calls)
+  - valid `Batch XY` within range → `process()` proceeds normally and produces
+    annotations (no `sendError`)
+  - `validate_coordinates()` called directly raises on out-of-range and returns
+    `None` when valid
+
+Run locally:
+
+```bash
+cd annotation_utilities && python -m pytest tests/ -q
+cd ../worker_client && python -m pytest tests/ -q
+```
+
+## Out of scope / follow-ups
+
+- The ~26 decentralized workers that parse batch ranges or call
+  `coordinatesToFrameIndex()` directly. They can adopt
+  `coordinate_validation.find_out_of_range` / `format_out_of_range_message`
+  in a later pass.
+- Hardening `coordinatesToFrameIndex` in the NimbusImage repo to raise a
+  descriptive exception instead of a bare `KeyError` — tracked as a separate
+  GitHub issue on `arjunrajlaboratory/NimbusImage`.

From 527655a1ab2dc4c20e76a6b99d4c9cb1c4f4c6b0 Mon Sep 17 00:00:00 2001
From: Arjun Raj <arjunrajlab@gmail.com>
Date: Sat, 30 May 2026 16:04:06 -0400
Subject: [PATCH 2/7] docs: tighten error message wording in
 coordinate-validation spec

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...t-of-range-coordinate-validation-design.md | 22 ++++++++++++++-----
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/docs/superpowers/specs/2026-05-30-out-of-range-coordinate-validation-design.md b/docs/superpowers/specs/2026-05-30-out-of-range-coordinate-validation-design.md
index 90b53cb..54a0468 100644
--- a/docs/superpowers/specs/2026-05-30-out-of-range-coordinate-validation-design.md
+++ b/docs/superpowers/specs/2026-05-30-out-of-range-coordinate-validation-design.md
@@ -73,16 +73,26 @@ def find_out_of_range(index_range, xys=None, zs=None, times=None):
     Dimensions passed as None are skipped."""
 
 def format_out_of_range_message(invalid):
-    """Build a single (message, info) pair for sendError. XY/Z/Time values are
-    reported 1-INDEXED to match what the user typed in the 'Batch XY/Z/Time' UI
-    fields (the batch parser converts 1->0 on input). Contiguous runs collapse
-    to 'a-b'; otherwise a comma-separated list."""
+    """Build a single (message, info) pair for sendError. Kept short because the
+    error display is compact. XY/Z/Time values are reported 1-INDEXED to match
+    what the user typed in the 'Batch XY/Z/Time' UI fields (the batch parser
+    converts 1->0 on input). Contiguous runs collapse to 'a-b'; otherwise a
+    comma-separated list.
+
+    Single offending dimension:
+      message = "Batch <label> out of range"
+      info    = "Position(s) <ranges> do not exist"
+    Multiple offending dimensions:
+      message = "Batch coordinates out of range"
+      info    = "Batch XY: positions <ranges> do not exist; Batch Z: ..."
+    Singular vs. plural ("Position 5 does not exist" vs. "Positions 81-91 do
+    not exist") is handled for a clean read."""
 ```
 
 Example output for the reported bug:
 
-> **message:** `"Batch XY is out of range"`
-> **info:** `"You requested XY position(s) 81-91, but this dataset has only 1 XY position (valid: 1). Please adjust the 'Batch XY' field."`
+> **message:** `"Batch XY out of range"`
+> **info:** `"Positions 81-91 do not exist"`
 
 `dim` → UI label mapping for messages: `XY` → "Batch XY", `Z` → "Batch Z",
 `Time` → "Batch Time".

From e6c5768382ac80d427f6352f15759cb304b04b03 Mon Sep 17 00:00:00 2001
From: Arjun Raj <arjunrajlab@gmail.com>
Date: Sat, 30 May 2026 16:09:43 -0400
Subject: [PATCH 3/7] fix: report actionable error for out-of-range batch
 coordinates

Workers using WorkerClient.process() crashed with a bare KeyError from
coordinatesToFrameIndex when a user's Batch XY/Z/Time range included
coordinates not present in the dataset (e.g. Batch XY '80-90' on a
single-XY dataset). The user saw only a stack trace.

Add a pure validator in annotation_utilities.coordinate_validation that
checks requested coordinates against the dataset's IndexRange and renders
a short, 1-indexed message matching the UI Batch fields. Wire it into a
new WorkerClient.validate_coordinates() that process() calls before the
loop (strict: any out-of-range coordinate -> sendError + raise). Call it
early in cellposesam.compute() so it fails before the GPU model loads.

Covers the 6 workers on the WorkerClient.process() path. The ~26 workers
that parse batch ranges directly can adopt the shared helper later; the
low-level coordinatesToFrameIndex hardening is tracked in
arjunrajlaboratory/NimbusImage#1185.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../coordinate_validation.py                  |  93 +++++++++++++++
 .../tests/test_coordinate_validation.py       | 103 +++++++++++++++++
 .../tests/test_worker_client_index_range.py   | 107 +++++++++++++++++-
 worker_client/worker_client/worker_client.py  |  43 ++++++-
 workers/annotations/cellposesam/entrypoint.py |   4 +
 5 files changed, 345 insertions(+), 5 deletions(-)
 create mode 100644 annotation_utilities/annotation_utilities/coordinate_validation.py
 create mode 100644 annotation_utilities/tests/test_coordinate_validation.py

diff --git a/annotation_utilities/annotation_utilities/coordinate_validation.py b/annotation_utilities/annotation_utilities/coordinate_validation.py
new file mode 100644
index 0000000..bdf6a5e
--- /dev/null
+++ b/annotation_utilities/annotation_utilities/coordinate_validation.py
@@ -0,0 +1,93 @@
+"""Validate batch coordinates against a dataset's dimensions.
+
+These are pure helpers (no I/O, no ``sendError``) so they can be unit-tested
+directly and reused by any worker. The caller decides what to do with the
+result (typically ``sendError`` + raise).
+
+Coordinates are 0-indexed internally (as the batch parser emits them after its
+1->0 conversion), but messages are rendered 1-indexed to match what the user
+typed in the 'Batch XY/Z/Time' UI fields.
+"""
+
+# Dimension key in tiles['IndexRange'] for each dimension we validate.
+INDEX_KEYS = {'XY': 'IndexXY', 'Z': 'IndexZ', 'Time': 'IndexT'}
+
+# Human-facing label (matches the UI field name) for each dimension.
+LABELS = {'XY': 'Batch XY', 'Z': 'Batch Z', 'Time': 'Batch Time'}
+
+# Stable order in which dimensions appear in combined messages.
+_ORDER = ('XY', 'Z', 'Time')
+
+
+def _dimension_size(index_range, dim):
+    """Number of positions along ``dim``; defaults to 1 when unknown.
+
+    A missing ``IndexRange`` or a missing per-dimension key both mean the
+    dataset has a single position along that dimension (only coord 0 valid),
+    matching the existing fallback convention used elsewhere in the repo.
+    """
+    if not index_range:
+        return 1
+    return index_range.get(INDEX_KEYS[dim], 1)
+
+
+def find_out_of_range(index_range, xys=None, zs=None, times=None):
+    """Find requested coordinates that fall outside the dataset.
+
+    :param dict index_range: ``tiles['IndexRange']`` (may be empty/missing keys).
+    :param xys/zs/times: iterables of requested 0-indexed coordinates, or
+        ``None`` to skip that dimension.
+    :return: ``{dim: (sorted_bad_0indexed_values, dimension_size)}`` for every
+        dimension with at least one out-of-range coordinate. Empty dict means
+        everything requested is valid.
+    """
+    requested = (('XY', xys), ('Z', zs), ('Time', times))
+    invalid = {}
+    for dim, values in requested:
+        if values is None:
+            continue
+        size = _dimension_size(index_range, dim)
+        bad = sorted({v for v in values if v < 0 or v >= size})
+        if bad:
+            invalid[dim] = (bad, size)
+    return invalid
+
+
+def _phrase(bad_zero_indexed, capitalized):
+    """Render a list of bad 0-indexed coordinates as a 1-indexed phrase."""
+    one_indexed = sorted(v + 1 for v in bad_zero_indexed)
+    if (len(one_indexed) > 1
+            and one_indexed[-1] - one_indexed[0] + 1 == len(one_indexed)):
+        span = f"{one_indexed[0]}-{one_indexed[-1]}"
+    else:
+        span = ", ".join(str(v) for v in one_indexed)
+
+    if len(one_indexed) == 1:
+        noun, verb = "Position", "does"
+    else:
+        noun, verb = "Positions", "do"
+    if not capitalized:
+        noun = noun.lower()
+    return f"{noun} {span} {verb} not exist"
+
+
+def format_out_of_range_message(invalid):
+    """Build a short ``(message, info)`` pair for ``sendError``.
+
+    :param invalid: the dict returned by :func:`find_out_of_range` (non-empty).
+    :return: ``(message, info)``. For a single offending dimension the message
+        is e.g. ``"Batch XY out of range"`` / ``"Positions 80-90 do not exist"``;
+        for several, ``"Batch coordinates out of range"`` and a combined info.
+    """
+    dims = [d for d in _ORDER if d in invalid]
+
+    if len(dims) == 1:
+        dim = dims[0]
+        bad, _size = invalid[dim]
+        return f"{LABELS[dim]} out of range", _phrase(bad, capitalized=True)
+
+    parts = []
+    for dim in dims:
+        bad, _size = invalid[dim]
+        parts.append(f"{LABELS[dim]}: {_phrase(bad, capitalized=False)}")
+    return "Batch coordinates out of range", "; ".join(parts)
diff --git a/annotation_utilities/tests/test_coordinate_validation.py b/annotation_utilities/tests/test_coordinate_validation.py
new file mode 100644
index 0000000..1672681
--- /dev/null
+++ b/annotation_utilities/tests/test_coordinate_validation.py
@@ -0,0 +1,103 @@
+import sys
+from pathlib import Path
+
+package_root = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(package_root))
+
+from annotation_utilities import coordinate_validation as cv
+
+
+# ---------------------------------------------------------------------------
+# find_out_of_range
+# ---------------------------------------------------------------------------
+
+def test_all_in_range_returns_empty():
+    assert cv.find_out_of_range({'IndexXY': 5}, xys=[0, 1, 4]) == {}
+
+
+def test_xy_out_of_range_detected_with_size():
+    # size 5 => valid 0-indexed 0..4; 5 and 6 are out of range
+    assert cv.find_out_of_range({'IndexXY': 5}, xys=[4, 5, 6]) == {
+        'XY': ([5, 6], 5)
+    }
+
+
+def test_missing_index_range_defaults_size_to_one():
+    # No IndexRange at all => every dimension has size 1 (only coord 0 valid)
+    assert cv.find_out_of_range({}, xys=[0]) == {}
+    assert cv.find_out_of_range({}, xys=[1]) == {'XY': ([1], 1)}
+
+
+def test_missing_subkey_defaults_that_dimension_to_one():
+    # IndexXY present but IndexZ absent => Z size defaults to 1
+    index_range = {'IndexXY': 3}
+    assert cv.find_out_of_range(index_range, zs=[0]) == {}
+    assert cv.find_out_of_range(index_range, zs=[1]) == {'Z': ([1], 1)}
+
+
+def test_negative_coordinate_is_out_of_range():
+    assert cv.find_out_of_range({'IndexXY': 5}, xys=[-1]) == {'XY': ([-1], 5)}
+
+
+def test_multiple_dimensions_reported_together():
+    index_range = {'IndexXY': 2, 'IndexZ': 2, 'IndexT': 2}
+    result = cv.find_out_of_range(index_range, xys=[2], zs=[0], times=[5, 6])
+    assert result == {'XY': ([2], 2), 'Time': ([5, 6], 2)}
+
+
+def test_none_dimensions_are_skipped():
+    # zs is None => never checked, even though it would be out of range
+    assert cv.find_out_of_range({'IndexXY': 5}, xys=[0]) == {}
+
+
+def test_bad_values_are_sorted_and_deduplicated():
+    assert cv.find_out_of_range({'IndexXY': 5}, xys=[6, 5, 6, 5]) == {
+        'XY': ([5, 6], 5)
+    }
+
+
+def test_empty_requested_list_is_in_range():
+    assert cv.find_out_of_range({'IndexXY': 1}, xys=[]) == {}
+
+
+# ---------------------------------------------------------------------------
+# format_out_of_range_message
+# ---------------------------------------------------------------------------
+
+def test_message_single_contiguous_range_is_one_indexed():
+    # 0-indexed 79..89 (the reported "80-90" input) => display 80-90
+    invalid = {'XY': (list(range(79, 90)), 1)}
+    message, info = cv.format_out_of_range_message(invalid)
+    assert message == 'Batch XY out of range'
+    assert info == 'Positions 80-90 do not exist'
+
+
+def test_message_single_position_is_singular():
+    invalid = {'Z': ([4], 1)}
+    message, info = cv.format_out_of_range_message(invalid)
+    assert message == 'Batch Z out of range'
+    assert info == 'Position 5 does not exist'
+
+
+def test_message_non_contiguous_positions_are_comma_listed():
+    invalid = {'XY': ([4, 6], 5)}
+    message, info = cv.format_out_of_range_message(invalid)
+    assert message == 'Batch XY out of range'
+    assert info == 'Positions 5, 7 do not exist'
+
+
+def test_message_multiple_dimensions_combined():
+    invalid = {'XY': ([79, 80], 1), 'Z': ([4], 1)}
+    message, info = cv.format_out_of_range_message(invalid)
+    assert message == 'Batch coordinates out of range'
+    assert info == (
+        'Batch XY: positions 80-81 do not exist; '
+        'Batch Z: position 5 does not exist'
+    )
+
+
+def test_message_uses_correct_labels_for_each_dimension():
+    _, info = cv.format_out_of_range_message({'Time': ([9], 5)})
+    message, _ = cv.format_out_of_range_message({'Time': ([9], 5)})
+    assert message == 'Batch Time out of range'
+    assert info == 'Position 10 does not exist'
diff --git a/worker_client/tests/test_worker_client_index_range.py b/worker_client/tests/test_worker_client_index_range.py
index c5d07dc..af91f59 100644
--- a/worker_client/tests/test_worker_client_index_range.py
+++ b/worker_client/tests/test_worker_client_index_range.py
@@ -4,9 +4,10 @@
 from pathlib import Path
 
 import numpy as np
+import pytest
 
 
-def _load_worker_client(monkeypatch, dataset_client):
+def _load_worker_client(monkeypatch, dataset_client, send_error_calls=None):
     package_root = Path(__file__).resolve().parents[1]
     monkeypatch.syspath_prepend(str(package_root))
 
@@ -18,6 +19,9 @@ def _load_worker_client(monkeypatch, dataset_client):
     annotations.UPennContrastAnnotationClient = lambda **kwargs: types.SimpleNamespace()
     tiles.UPennContrastDataset = lambda **kwargs: dataset_client
     utils.sendProgress = lambda *args, **kwargs: None
+    if send_error_calls is None:
+        send_error_calls = []
+    utils.sendError = lambda *args, **kwargs: send_error_calls.append((args, kwargs))
 
     monkeypatch.setitem(sys.modules, "annotation_client", annotation_client)
     monkeypatch.setitem(sys.modules, "annotation_client.annotations", annotations)
@@ -88,3 +92,104 @@ def test_get_image_stack_uses_index_range_when_present(monkeypatch):
         (0, 0, 0, 1),
         (0, 0, 0, 2),
     ]
+
+
+# ---------------------------------------------------------------------------
+# Out-of-range coordinate validation
+# ---------------------------------------------------------------------------
+
+def _batch_params(**worker_interface):
+    return {
+        "assignment": {},
+        "channel": 0,
+        "connectTo": {"tags": []},
+        "tags": [],
+        "tile": {"XY": 0, "Z": 0, "Time": 0},
+        "workerInterface": worker_interface,
+    }
+
+
+def test_process_raises_and_sends_error_on_out_of_range_xy(monkeypatch):
+    dataset_client = DummyDatasetClient(tiles={"IndexRange": {"IndexXY": 1}})
+    send_error_calls = []
+    WorkerClient = _load_worker_client(monkeypatch, dataset_client, send_error_calls)
+    worker = WorkerClient("dataset", "http://api", "token",
+                          _batch_params(**{"Batch XY": "80-90"}))
+
+    with pytest.raises(ValueError):
+        worker.process(lambda image: [], lambda location, output: None)
+
+    assert len(send_error_calls) == 1
+    assert send_error_calls[0][0][0] == "Batch XY out of range"
+    assert send_error_calls[0][1]["info"] == "Positions 80-90 do not exist"
+    # The processing loop must never run when validation fails.
+    assert dataset_client.frame_requests == []
+
+
+def test_process_succeeds_for_in_range_xy(monkeypatch):
+    dataset_client = DummyDatasetClient(tiles={"IndexRange": {"IndexXY": 5}})
+    send_error_calls = []
+    WorkerClient = _load_worker_client(monkeypatch, dataset_client, send_error_calls)
+    worker = WorkerClient("dataset", "http://api", "token",
+                          _batch_params(**{"Batch XY": "1-3"}))
+
+    annotated = []
+    worker.process(lambda image: image,
+                   lambda location, output: annotated.append(location))
+
+    assert send_error_calls == []
+    # Batch XY 1-3 (1-indexed) -> 0-indexed 0, 1, 2 -> three iterations.
+    assert dataset_client.frame_requests == [(0, 0, 0, 0), (1, 0, 0, 0), (2, 0, 0, 0)]
+    assert annotated == [(0, 0, 0, 0), (1, 0, 0, 0), (2, 0, 0, 0)]
+
+
+def test_process_errors_when_index_range_missing_and_coord_nonzero(monkeypatch):
+    # No IndexRange => every dimension defaults to size 1 (only position 1 valid).
+    dataset_client = DummyDatasetClient(tiles={})
+    send_error_calls = []
+    WorkerClient = _load_worker_client(monkeypatch, dataset_client, send_error_calls)
+    worker = WorkerClient("dataset", "http://api", "token",
+                          _batch_params(**{"Batch XY": "2"}))
+
+    with pytest.raises(ValueError):
+        worker.process(lambda image: [], lambda location, output: None)
+
+    assert len(send_error_calls) == 1
+    assert dataset_client.frame_requests == []
+
+
+def test_validate_coordinates_raises_directly(monkeypatch):
+    dataset_client = DummyDatasetClient(tiles={"IndexRange": {"IndexXY": 1}})
+    send_error_calls = []
+    WorkerClient = _load_worker_client(monkeypatch, dataset_client, send_error_calls)
+    worker = WorkerClient("dataset", "http://api", "token",
+                          _batch_params(**{"Batch XY": "80-90"}))
+
+    with pytest.raises(ValueError):
+        worker.validate_coordinates()
+
+    assert send_error_calls[0][1]["info"] == "Positions 80-90 do not exist"
+
+
+def test_validate_coordinates_returns_none_when_in_range(monkeypatch):
+    dataset_client = DummyDatasetClient(tiles={"IndexRange": {"IndexXY": 5}})
+    send_error_calls = []
+    WorkerClient = _load_worker_client(monkeypatch, dataset_client, send_error_calls)
+    worker = WorkerClient("dataset", "http://api", "token",
+                          _batch_params(**{"Batch XY": "1-3"}))
+
+    assert worker.validate_coordinates() is None
+    assert send_error_calls == []
+
+
+def test_validate_coordinates_skips_stacked_dimension(monkeypatch):
+    # Batch XY is out of range, but when XY is STACKED (not batched) the worker
+    # uses the current (valid) tile XY instead, so validation must not fire.
+    dataset_client = DummyDatasetClient(tiles={"IndexRange": {"IndexXY": 1}})
+    send_error_calls = []
+    WorkerClient = _load_worker_client(monkeypatch, dataset_client, send_error_calls)
+    worker = WorkerClient("dataset", "http://api", "token",
+                          _batch_params(**{"Batch XY": "80-90"}))
+
+    assert worker.validate_coordinates(stack_xys=[0]) is None
+    assert send_error_calls == []
diff --git a/worker_client/worker_client/worker_client.py b/worker_client/worker_client/worker_client.py
index e5afd81..8842c3e 100644
--- a/worker_client/worker_client/worker_client.py
+++ b/worker_client/worker_client/worker_client.py
@@ -9,8 +9,9 @@
 import annotation_client.annotations as annotations
 import annotation_client.tiles as tiles
 
-from annotation_client.utils import sendProgress
+from annotation_client.utils import sendProgress, sendError
 from annotation_utilities import batch_argument_parser
+from annotation_utilities import coordinate_validation
 
 
 class WorkerClient:
@@ -56,9 +57,11 @@ def __init__(self, datasetId, apiUrl, token, params):
         if batch_time is None:
             batch_time = [tile['Time']]
 
-        self.batch_xy = batch_xy
-        self.batch_z = batch_z
-        self.batch_time = batch_time
+        # Materialize to lists: process_range_list returns a one-shot generator,
+        # and these are now read by both validate_coordinates() and process().
+        self.batch_xy = list(batch_xy)
+        self.batch_z = list(batch_z)
+        self.batch_time = list(batch_time)
 
         annotationClient = annotations.UPennContrastAnnotationClient(
             apiUrl=apiUrl, token=token)
@@ -230,6 +233,34 @@ def create_polygon_annotations(self, location, polygons):
             self.annotationClient.connectToNearest(
                 self.connectTo, annotationsIds)
 
+    def validate_coordinates(self, stack_xys=None, stack_zs=None, stack_times=None):
+        """Validate the batch coordinates that will be iterated against the
+        dataset's dimensions.
+
+        If any requested XY/Z/Time coordinate is out of range, report an
+        actionable message via ``sendError`` and raise ``ValueError``. A
+        dimension the worker stacks (its ``stack_*`` is not ``None``) is
+        validated against the current tile coordinate, which is valid by
+        construction, so only batched dimensions are really checked.
+
+        Safe to call early (e.g. before loading an expensive model); the
+        ``stack_*`` arguments must match those passed to :meth:`process`.
+        ``process`` calls this too. Returns ``None`` when everything is in
+        range.
+        """
+        xys = list(self.batch_xy) if stack_xys is None else [self.tile['XY']]
+        zs = list(self.batch_z) if stack_zs is None else [self.tile['Z']]
+        times = list(self.batch_time) if stack_times is None else [self.tile['Time']]
+
+        index_range = self.datasetClient.tiles.get('IndexRange', {})
+        invalid = coordinate_validation.find_out_of_range(
+            index_range, xys=xys, zs=zs, times=times)
+        if invalid:
+            message, info = coordinate_validation.format_out_of_range_message(
+                invalid)
+            sendError(message, info=info)
+            raise ValueError(message)
+
     def process(self, f_process, f_annotation, stack_xys=None, stack_zs=None, stack_times=None, stack_channels=None,
                 progress_text='Running Worker'):
 
@@ -238,6 +269,10 @@ def process(self, f_process, f_annotation, stack_xys=None, stack_zs=None, stack_
         elif f_annotation == 'polygon':
             f_annotation = self.create_polygon_annotations
 
+        # Fail fast with an actionable error before doing any work if the
+        # requested batch coordinates fall outside the dataset.
+        self.validate_coordinates(stack_xys, stack_zs, stack_times)
+
         batch = []
         if stack_xys is None:
             batch.append(list(self.batch_xy))
diff --git a/workers/annotations/cellposesam/entrypoint.py b/workers/annotations/cellposesam/entrypoint.py
index 414a207..8849ced 100644
--- a/workers/annotations/cellposesam/entrypoint.py
+++ b/workers/annotations/cellposesam/entrypoint.py
@@ -193,6 +193,10 @@ def compute(datasetId, apiUrl, token, params):
 
     worker = WorkerClient(datasetId, apiUrl, token, params)
 
+    # Fail fast with an actionable error if the requested Batch XY/Z/Time
+    # coordinates are out of range, before loading the (slow) Cellpose-SAM model.
+    worker.validate_coordinates()
+
     # Get the model and diameter from interface values
     model = worker.workerInterface['Model']
     diameter = float(worker.workerInterface['Diameter'])

From 42691064b5786ea66e4fbda6f94f400b23485658 Mon Sep 17 00:00:00 2001
From: Arjun Raj <arjunrajlab@gmail.com>
Date: Sat, 30 May 2026 16:11:07 -0400
Subject: [PATCH 4/7] docs: track deferred out-of-range validation rollout
 (TODO-002)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 todo/TODO_REGISTRY.md                         |  1 +
 ...-of-range-coordinate-validation-rollout.md | 81 +++++++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 todo/out-of-range-coordinate-validation-rollout.md

diff --git a/todo/TODO_REGISTRY.md b/todo/TODO_REGISTRY.md
index 7454a27..4b0bf27 100644
--- a/todo/TODO_REGISTRY.md
+++ b/todo/TODO_REGISTRY.md
@@ -13,6 +13,7 @@ Master index of deferred work, technical debt, and future improvements for the I
 | ID | Title | Status | Priority | File | Related PR |
 |----|-------|--------|----------|------|------------|
 | TODO-001 | ML worker build optimization (mamba + shared base images) | Deferred | Medium | [ml-worker-build-optimization.md](ml-worker-build-optimization.md) | [#132](https://github.com/arjunrajlaboratory/ImageAnalysisProject/pull/132) |
+| TODO-002 | Roll out out-of-range coordinate validation to remaining workers | Deferred | Medium | [out-of-range-coordinate-validation-rollout.md](out-of-range-coordinate-validation-rollout.md) | `fix-batch-coordinate-out-of-range` |
 
 ## Completed TODOs
 
diff --git a/todo/out-of-range-coordinate-validation-rollout.md b/todo/out-of-range-coordinate-validation-rollout.md
new file mode 100644
index 0000000..7c95d9c
--- /dev/null
+++ b/todo/out-of-range-coordinate-validation-rollout.md
@@ -0,0 +1,81 @@
+# TODO-002: Roll out out-of-range coordinate validation to remaining workers
+
+**Status:** Deferred
+**Priority:** Medium
+**Related branch/PR:** `fix-batch-coordinate-out-of-range`
+**Related issue:** [NimbusImage#1185](https://github.com/arjunrajlaboratory/NimbusImage/issues/1185)
+**Design spec:** [docs/superpowers/specs/2026-05-30-out-of-range-coordinate-validation-design.md](../docs/superpowers/specs/2026-05-30-out-of-range-coordinate-validation-design.md)
+
+## Summary
+
+When a user enters a `Batch XY`, `Batch Z`, or `Batch Time` range that includes
+coordinates not present in the dataset, workers crash with a bare `KeyError`
+from `coordinatesToFrameIndex` (`self.map[channel][T][Z][XY]`) instead of an
+actionable message.
+
+The initial fix (this branch) added a shared, pure validator
+(`annotation_utilities.coordinate_validation.find_out_of_range` /
+`format_out_of_range_message`) and wired it into `WorkerClient.process()` via a
+new `WorkerClient.validate_coordinates()`. That covers **only the workers on the
+`WorkerClient.process()` path**:
+
+- cellposesam (also gets an early `validate_coordinates()` call before model load)
+- cellpose
+- condensatenet
+- laplacian_of_gaussian
+- random_squares
+- sample_interface
+
+This TODO tracks extending the same protection to the workers that parse batch
+ranges and/or call `coordinatesToFrameIndex()` **directly**, which still crash
+with a bare `KeyError`.
+
+## Remaining work — workers that need individual fixes
+
+These parse batch ranges (`process_range_list` / `get_batch_information`) and
+iterate `coordinatesToFrameIndex()` / `getRegion()` themselves. They should call
+`coordinate_validation.find_out_of_range` + `format_out_of_range_message`
+(then `sendError` + raise) before their processing loop:
+
+- `workers/annotations/cellori_segmentation/entrypoint.py` (~L86-117)
+- `workers/annotations/sam2_automatic_mask_generator/entrypoint.py` (~L86-88, 127)
+- `workers/annotations/sam2_refine/entrypoint.py` (~L198-200, 303)
+- `workers/annotations/sam2_propagate/entrypoint.py` (~L310-312, 379, 431)
+- `workers/annotations/sam2_video/entrypoint.py` (~L217-219)
+- `workers/annotations/sam_fewshot_segmentation/entrypoint.py` (~L268-270, 347, 420)
+- `workers/annotations/sam2_fewshot_segmentation/entrypoint.py` (~L268-270, 331, 404)
+- `workers/annotations/cellpose_train/entrypoint.py` (~L252-258)
+- `workers/annotations/histogram_matching/entrypoint.py` (~L122)
+
+Shared helper that several SAM workers funnel through (fixing it here protects
+all its callers):
+
+- `annotation_utilities/annotation_utilities/annotation_tools.py` →
+  `get_images_for_all_channels()` (~L213-225) calls `coordinatesToFrameIndex()`.
+
+## Already validate (no change needed — and good reference patterns)
+
+- `workers/annotations/registration/entrypoint.py` — validates reference Z/Time
+  against `IndexRange`; intersects parsed batch ranges with valid ranges.
+- `workers/annotations/crop/entrypoint.py` — intersects all three batch ranges
+  with the dataset ranges.
+- `workers/properties/blobs/blob_intensity_worker/entrypoint.py` and
+  `blob_annulus_intensity_worker` — build `range_z = range(0, IndexZ)`, filter
+  Z planes, and `sendWarning` for out-of-range. (Note: these use a *filter +
+  warn* policy; the WorkerClient fix uses *strict error*. Decide per worker
+  whether to keep filter-and-warn or move to strict on rollout.)
+
+## Lower-risk (preview functions — single tile)
+
+These load a single tile in their `interface`/preview path; lower risk but still
+vulnerable if a user edits batch params:
+random_point, random_point_annotation_M1, annulus_generator_M1, gaussian_blur,
+rolling_ball, deepcell, stardist, laplacian_of_gaussian (preview).
+
+## Notes
+
+- Property workers that iterate **annotation-sourced** locations (not user batch
+  ranges) are lower risk, since locations come from existing annotations; the
+  main exposure there is the channel index, which the UI constrains.
+- Defense-in-depth at the lowest level (`coordinatesToFrameIndex` raising a
+  descriptive exception) is tracked separately in NimbusImage#1185.

From d7d2faf446b5964ff3df12775e55389df585638d Mon Sep 17 00:00:00 2001
From: Arjun Raj <arjunrajlab@gmail.com>
Date: Sat, 30 May 2026 16:18:35 -0400
Subject: [PATCH 5/7] test: cover Batch Z and multi-dimension out-of-range
 through process()

Closes a coverage gap noted in code review: process()-level validation
was only exercised via Batch XY. Add integration tests for an
out-of-range Batch Z and for the combined multi-dimension error message.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../tests/test_worker_client_index_range.py   | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/worker_client/tests/test_worker_client_index_range.py b/worker_client/tests/test_worker_client_index_range.py
index af91f59..3d009d2 100644
--- a/worker_client/tests/test_worker_client_index_range.py
+++ b/worker_client/tests/test_worker_client_index_range.py
@@ -158,6 +158,44 @@ def test_process_errors_when_index_range_missing_and_coord_nonzero(monkeypatch):
     assert dataset_client.frame_requests == []
 
 
+def test_process_raises_and_sends_error_on_out_of_range_z(monkeypatch):
+    # Exercise a non-XY dimension through process() to lock in per-dimension
+    # wiring (Batch XY is left in range / unspecified).
+    dataset_client = DummyDatasetClient(tiles={"IndexRange": {"IndexZ": 1}})
+    send_error_calls = []
+    WorkerClient = _load_worker_client(monkeypatch, dataset_client, send_error_calls)
+    worker = WorkerClient("dataset", "http://api", "token",
+                          _batch_params(**{"Batch Z": "3-4"}))
+
+    with pytest.raises(ValueError):
+        worker.process(lambda image: [], lambda location, output: None)
+
+    assert len(send_error_calls) == 1
+    assert send_error_calls[0][0][0] == "Batch Z out of range"
+    assert send_error_calls[0][1]["info"] == "Positions 3-4 do not exist"
+    assert dataset_client.frame_requests == []
+
+
+def test_process_reports_multiple_out_of_range_dimensions(monkeypatch):
+    dataset_client = DummyDatasetClient(
+        tiles={"IndexRange": {"IndexXY": 1, "IndexZ": 1}})
+    send_error_calls = []
+    WorkerClient = _load_worker_client(monkeypatch, dataset_client, send_error_calls)
+    worker = WorkerClient("dataset", "http://api", "token",
+                          _batch_params(**{"Batch XY": "5", "Batch Z": "3-4"}))
+
+    with pytest.raises(ValueError):
+        worker.process(lambda image: [], lambda location, output: None)
+
+    assert len(send_error_calls) == 1
+    assert send_error_calls[0][0][0] == "Batch coordinates out of range"
+    assert send_error_calls[0][1]["info"] == (
+        "Batch XY: position 5 does not exist; "
+        "Batch Z: positions 3-4 do not exist"
+    )
+    assert dataset_client.frame_requests == []
+
+
 def test_validate_coordinates_raises_directly(monkeypatch):
     dataset_client = DummyDatasetClient(tiles={"IndexRange": {"IndexXY": 1}})
     send_error_calls = []

From 0895756c87644c923f940716f9759109c1239362 Mon Sep 17 00:00:00 2001
From: Arjun Raj <arjunrajlab@gmail.com>
Date: Sat, 30 May 2026 16:20:03 -0400
Subject: [PATCH 6/7] chore: regenerate REGISTRY.md (required by pre-PR
 worker-docs hook)

Triggered by the internal-only cellposesam entrypoint edit. The diff is
pre-existing description drift between REGISTRY.md and current worker
interfaces; it is unrelated to the coordinate-validation fix and is
included only to satisfy the repo's doc-sync hooks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 REGISTRY.md | 42 +++++++++++++++++++++---------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/REGISTRY.md b/REGISTRY.md
index ab9febd..09c9e47 100644
--- a/REGISTRY.md
+++ b/REGISTRY.md
@@ -23,8 +23,8 @@ Create new annotations by segmenting images or connecting existing annotations.
 |--------|-------------|-----|-------|------|
 | Claude natural language analyzer | Uses Claude AI to analyze images |  |  | [docs](workers/annotations/ai_analysis/AI_ANALYSIS.md) |
 | Cellori Segmentation |  | Yes |  | [docs](workers/annotations/cellori_segmentation/CELLORI_SEGMENTATION.md) |
-| Cellpose | Uses Cellpose to find cells and nuclei | Yes |  | [docs](workers/annotations/cellpose/CELLPOSE.md) |
-| Cellpose retrain | Retrains Cellpose models based on user-selected images | Yes |  | [docs](workers/annotations/cellpose_train/CELLPOSE_TRAIN.md) |
+| Cellpose | This tool runs the Cellpose model to segment the image into cells. Learn more | Yes |  | [docs](workers/annotations/cellpose/CELLPOSE.md) |
+| Cellpose retrain | This tool trains a Cellpose model using user-corrected annotations. Learn more | Yes |  | [docs](workers/annotations/cellpose_train/CELLPOSE_TRAIN.md) |
 | Cellpose-SAM | This tool runs the Cellpose-SAM model to segment the image into cells. Learn more | Yes |  | [docs](workers/annotations/cellposesam/CELLPOSESAM.md) |
 | CondensateNet segmentation | Segments biomolecular condensates using CondensateNet deep learning model | Yes |  | [docs](workers/annotations/condensatenet/CONDENSATENET.md) |
 | Connect Sequential | This tool connects objects sequentially across time or z-slices.It is useful for connec... |  | Yes | [docs](workers/annotations/connect_sequential/CONNECT_SEQUENTIAL.md) |
@@ -36,13 +36,13 @@ Create new annotations by segmenting images or connecting existing annotations.
 | Gaussian Blur | Applies Gaussian blur to images |  | Yes | [docs](workers/annotations/gaussian_blur/GAUSSIAN_BLUR.md) |
 | H&E Deconvolution | Deconvolves H&E stains |  | Yes | [docs](workers/annotations/h_and_e_deconvolution/H_AND_E_DECONVOLUTION.md) |
 | Histogram Matching | Corrects images using histogram matching |  | Yes | [docs](workers/annotations/histogram_matching/HISTOGRAM_MATCHING.md) |
-| Laplacian of Gaussian | Detects spots in images using the Laplacian of Gaussian method |  |  | [docs](workers/annotations/laplacian_of_gaussian/LAPLACIAN_OF_GAUSSIAN.md) |
+| Laplacian of Gaussian | This tool finds spots in an image using the Laplacian of Gaussian method.It uses a filt... |  |  | [docs](workers/annotations/laplacian_of_gaussian/LAPLACIAN_OF_GAUSSIAN.md) |
 | Time lapse registration | Corrects images using time lapse registration |  | Yes | [docs](workers/annotations/registration/REGISTRATION.md) |
 | Rolling Ball | Corrects images using a rolling ball |  | Yes | [docs](workers/annotations/rolling_ball/ROLLING_BALL.md) |
 | SAM2 automatic mask generator | Uses SAM2 to find all masks in the image | Yes |  | [docs](workers/annotations/sam2_automatic_mask_generator/SAM2_AUTOMATIC_MASK_GENERATOR.md) |
 | SAM2 few-shot segmentation | Uses SAM2 features for few-shot segmentation based on training annotations | Yes | Yes | [docs](workers/annotations/sam2_fewshot_segmentation/SAM2_FEWSHOT_SEGMENTATION.md) |
-| SAM2 propagator | Uses SAM2 to propagate annotations through time or Z-slices | Yes |  | [docs](workers/annotations/sam2_propagate/SAM2_PROPAGATE.md) |
-| SAM2 Refiner | Uses SAM2 to refine annotations | Yes |  | [docs](workers/annotations/sam2_refine/SAM2_REFINE.md) |
+| SAM2 propagator | This tool uses the SAM2 model to take an existing annotation and propagate it through t... | Yes |  | [docs](workers/annotations/sam2_propagate/SAM2_PROPAGATE.md) |
+| SAM2 Refiner | This tool uses the SAM2 model to refine existing annotations. It takes existing annotat... | Yes |  | [docs](workers/annotations/sam2_refine/SAM2_REFINE.md) |
 | SAM2 video | Uses SAM2 to track video through time or Z | Yes |  | [docs](workers/annotations/sam2_video/SAM2_VIDEO.md) |
 | SAM automatic mask generator | Uses SAM to find all masks in the image | Yes |  | [docs](workers/annotations/sam_automatic_mask_generator/SAM_AUTOMATIC_MASK_GENERATOR.md) |
 | SAM few-shot segmentation | Uses SAM1 ViT-H features for few-shot segmentation based on training annotations | Yes | Yes | [docs](workers/annotations/sam_fewshot_segmentation/SAM_FEWSHOT_SEGMENTATION.md) |
@@ -54,16 +54,16 @@ Compute properties on polygon / blob annotations.
 
 | Worker | Description | Tests | Docs |
 |--------|-------------|-------|------|
-| Annulus intensity percentile measurements | Compute intensity at a specific percentile for an annular region around blobs | Yes | [docs](workers/properties/blobs/blob_annulus_intensity_percentile_worker/BLOB_ANNULUS_INTENSITY_PERCENTILE_WORKER.md) |
-| Annulus intensity measurements | Compute intensity measurements (mean, median, etc.) for an annular region around blobs | Yes | [docs](workers/properties/blobs/blob_annulus_intensity_worker/BLOB_ANNULUS_INTENSITY_WORKER.md) |
+| Annulus intensity percentile measurements | This tool computes the pixel intensity in an annulus around the objects in the specifie... | Yes | [docs](workers/properties/blobs/blob_annulus_intensity_percentile_worker/BLOB_ANNULUS_INTENSITY_PERCENTILE_WORKER.md) |
+| Annulus intensity measurements | This tool computes the pixel intensity in an annulus around the objects in the specifie... | Yes | [docs](workers/properties/blobs/blob_annulus_intensity_worker/BLOB_ANNULUS_INTENSITY_WORKER.md) |
 | Colony two color intensity | Compute intensity across two channels for blobs; useful for colony intensity measurements |  | [docs](workers/properties/blobs/blob_colony_two_color_intensity_worker/BLOB_COLONY_TWO_COLOR_INTENSITY_WORKER.md) |
-| Blob intensity percentile measurements | Compute intensity at a specific percentile for blobs | Yes | [docs](workers/properties/blobs/blob_intensity_percentile_worker/BLOB_INTENSITY_PERCENTILE_WORKER.md) |
-| Blob intensity measurements | Compute intensity measurements (mean, median, etc.) for blobs | Yes | [docs](workers/properties/blobs/blob_intensity_worker/BLOB_INTENSITY_WORKER.md) |
-| Blob metrics | Compute area, perimeter, and other metrics for blobs | Yes | [docs](workers/properties/blobs/blob_metrics_worker/BLOB_METRICS_WORKER.md) |
-| Blob overlap | Compute overlap between blobs | Yes | [docs](workers/properties/blobs/blob_overlap_worker/BLOB_OVERLAP_WORKER.md) |
+| Blob intensity percentile measurements | This tool computes the pixel intensity of objects in the specified channel at the speci... | Yes | [docs](workers/properties/blobs/blob_intensity_percentile_worker/BLOB_INTENSITY_PERCENTILE_WORKER.md) |
+| Blob intensity measurements | This tool computes the pixel intensity of objects in the specified channel. It will com... | Yes | [docs](workers/properties/blobs/blob_intensity_worker/BLOB_INTENSITY_WORKER.md) |
+| Blob metrics | This tool computes a variety of metrics for the objects in the specified channel. The m... | Yes | [docs](workers/properties/blobs/blob_metrics_worker/BLOB_METRICS_WORKER.md) |
+| Blob overlap | This tool computes the overlaps between two sets of annotations. The overlap is compute... | Yes | [docs](workers/properties/blobs/blob_overlap_worker/BLOB_OVERLAP_WORKER.md) |
 | Point count 3D projection | Count points in a 3D projection |  | [docs](workers/properties/blobs/blob_point_count_3D_projection_worker/BLOB_POINT_COUNT_3D_PROJECTION_WORKER.md) |
-| Point count | Count the number of points that fall within a blob/polygon; can work in 2D or 3D | Yes | [docs](workers/properties/blobs/blob_point_count_worker/BLOB_POINT_COUNT_WORKER.md) |
-| Random Forest Classifier | Classify blobs using a Random Forest Classifier | Yes | [docs](workers/properties/blobs/blob_random_forest_classifier/BLOB_RANDOM_FOREST_CLASSIFIER.md) |
+| Point count | This tool counts the number of points within polygon annotations. The points will be of... | Yes | [docs](workers/properties/blobs/blob_point_count_worker/BLOB_POINT_COUNT_WORKER.md) |
+| Random Forest Classifier | This tool uses a Random Forest Classifier to classify blobs. | Yes | [docs](workers/properties/blobs/blob_random_forest_classifier/BLOB_RANDOM_FOREST_CLASSIFIER.md) |
 
 ## Property Workers -- Points
 
@@ -72,9 +72,9 @@ Compute properties on point annotations.
 | Worker | Description | Tests | Docs |
 |--------|-------------|-------|------|
 | Point circle intensity | Computes mean intensity metrics around a point; radius 1 for pixel precision |  | [docs](workers/properties/points/point_circle_intensity_mean_worker/POINT_CIRCLE_INTENSITY_MEAN_WORKER.md) |
-| Point intensity | Computes a variety of intensity metrics around a point; radius 1 for pixel precision | Yes | [docs](workers/properties/points/point_circle_intensity_worker/POINT_CIRCLE_INTENSITY_WORKER.md) |
+| Point intensity | This tool computes the average, maximum, minimum, median, total, 25th percentile, and 7... | Yes | [docs](workers/properties/points/point_circle_intensity_worker/POINT_CIRCLE_INTENSITY_WORKER.md) |
 | Point Intensity Worker |  |  | [docs](workers/properties/points/point_intensity_worker/POINT_INTENSITY_WORKER.md) |
-| Point metrics | Computes a variety of metrics for points, like X and Y coordinates | Yes | [docs](workers/properties/points/point_metrics_worker/POINT_METRICS_WORKER.md) |
+| Point metrics | This tool adds a property to the points to document their coordinates. It gives each po... | Yes | [docs](workers/properties/points/point_metrics_worker/POINT_METRICS_WORKER.md) |
 | Point Threshold Intensity Mean Worker |  |  | [docs](workers/properties/points/point_threshold_intensity_mean_worker/POINT_THRESHOLD_INTENSITY_MEAN_WORKER.md) |
 | Distance to nearest blob |  | Yes | [docs](workers/properties/points/point_to_nearest_blob_distance/POINT_TO_NEAREST_BLOB_DISTANCE.md) |
 | Distance from point to nearest other point |  |  | [docs](workers/properties/points/point_to_nearest_connected_point_distance/POINT_TO_NEAREST_CONNECTED_POINT_DISTANCE.md) |
@@ -86,8 +86,8 @@ Compute properties on line annotations.
 
 | Worker | Description | Tests | Docs |
 |--------|-------------|-------|------|
-| length | Compute the length of lines |  | [docs](workers/properties/lines/line_length_worker/LINE_LENGTH_WORKER.md) |
-| Line scan CSV | This tool computes the intensity along a line and puts the results in a CSV file. The i... |  | [docs](workers/properties/lines/line_scan_worker/LINE_SCAN_WORKER.md) |
+| length | Computes the length of lines. |  | [docs](workers/properties/lines/line_length_worker/LINE_LENGTH_WORKER.md) |
+| Line scan CSV | This tool computes the intensity along a line and puts the results in a CSV file. The i... | Yes | [docs](workers/properties/lines/line_scan_worker/LINE_SCAN_WORKER.md) |
 | Test File Creation |  |  | [docs](workers/properties/lines/test_file_creation_worker/TEST_FILE_CREATION_WORKER.md) |
 
 ## Property Workers -- Connections
@@ -96,8 +96,8 @@ Compute properties based on relationships between annotations.
 
 | Worker | Description | Tests | Docs |
 |--------|-------------|-------|------|
-| Count connected objects | Count the number of children objects that are connected to a parent polygon | Yes | [docs](workers/properties/connections/children_count_worker/CHILDREN_COUNT_WORKER.md) |
-| Connection IDs | Creates a set of identifiers that indicate the parent-child relationships between polygons | Yes | [docs](workers/properties/connections/parent_child_worker/PARENT_CHILD_WORKER.md) |
+| Count connected objects | This tool counts the number of children objects that are connected to a parent polygon.... | Yes | [docs](workers/properties/connections/children_count_worker/CHILDREN_COUNT_WORKER.md) |
+| Connection IDs | This tool adds a property to the objects to document the connections between them, whic... | Yes | [docs](workers/properties/connections/parent_child_worker/PARENT_CHILD_WORKER.md) |
 
 ## Test / Sample Workers
 
@@ -108,8 +108,8 @@ Workers used for testing and demonstration -- not intended for production use.
 | Annulus Generator M1 |  |  |  | [docs](workers/annotations/annulus_generator_M1/ANNULUS_GENERATOR_M1.md) |
 | Random point | Creates random point annotations |  |  | [docs](workers/annotations/random_point/RANDOM_POINT.md) |
 | Random Point Annotation M1 |  |  |  | [docs](workers/annotations/random_point_annotation_M1/RANDOM_POINT_ANNOTATION_M1.md) |
-| Random squares | Generates random square polygon annotations for testing |  | Yes | [docs](workers/annotations/random_squares/RANDOM_SQUARES.md) |
-| Sample interface | Demonstrates all interface types, messaging patterns, and batch mode |  | Yes | [docs](workers/annotations/sample_interface/SAMPLE_INTERFACE.md) |
+| Random squares | Generates random square polygon annotations within the image bounds. Useful for testing... |  | Yes | [docs](workers/annotations/random_squares/RANDOM_SQUARES.md) |
+| Sample interface | This is a sample interface worker that demonstrates all available interface types, tool... |  | Yes | [docs](workers/annotations/sample_interface/SAMPLE_INTERFACE.md) |
 | Test Multiple Annotation |  |  |  | [docs](workers/annotations/test_multiple_annotation/TEST_MULTIPLE_ANNOTATION.md) |
 | Test Multiple Annotation M1 |  |  |  | [docs](workers/annotations/test_multiple_annotation_M1/TEST_MULTIPLE_ANNOTATION_M1.md) |
 

From 7ae62a95a91bed271ae30fd67968495598be12b4 Mon Sep 17 00:00:00 2001
From: Arjun Raj <arjunrajlab@gmail.com>
Date: Sat, 30 May 2026 16:28:05 -0400
Subject: [PATCH 7/7] fix: guard cellposesam early validate_coordinates()
 against version-skewed worker_client

The cellposesam Dockerfile installs worker_client from a fresh master
clone while entrypoint.py is copied from the build context. A pre-merge
branch build therefore pairs the new entrypoint with an older
worker_client lacking validate_coordinates(), raising AttributeError on
every compute request. Guard the early call with hasattr; process() still
performs the same validation once worker_client is current.

Addresses Codex review (P2) on PR #143.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 workers/annotations/cellposesam/entrypoint.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/workers/annotations/cellposesam/entrypoint.py b/workers/annotations/cellposesam/entrypoint.py
index 8849ced..1a8a292 100644
--- a/workers/annotations/cellposesam/entrypoint.py
+++ b/workers/annotations/cellposesam/entrypoint.py
@@ -195,7 +195,12 @@ def compute(datasetId, apiUrl, token, params):
 
     # Fail fast with an actionable error if the requested Batch XY/Z/Time
     # coordinates are out of range, before loading the (slow) Cellpose-SAM model.
-    worker.validate_coordinates()
+    # Guarded with hasattr: this image installs worker_client from a master
+    # clone (see Dockerfile), so a pre-merge branch build may ship an older
+    # worker_client without this method. process() validates again regardless
+    # once worker_client is current, so skipping here only defers the check.
+    if hasattr(worker, "validate_coordinates"):
+        worker.validate_coordinates()
 
     # Get the model and diameter from interface values
     model = worker.workerInterface['Model']