gridlinegpu 0.1.4__tar.gz → 0.1.5__tar.gz

{gridlinegpu-0.1.4 → gridlinegpu-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridlinegpu
-Version: 0.1.4
+Version: 0.1.5
 Summary: Python client for Gridline YAML workload routing
 Author: Gridline GPU
 License: Proprietary
@@ -44,6 +44,8 @@ may still cap inputs at 40 MiB and outputs at 8 MiB.
 from gridlinegpu import GridlineClient
 
 client = GridlineClient()
+search = client.search("workload.yaml")
+print(search["coverage"], search["offers"])  # Catalog facts may be unknown; coverage may be partial.
 plan = client.plan("workload.yaml")
 print(plan.review)  # Check selected GPU, exclusions, estimate, and maximum.
 
@@ -58,6 +60,7 @@ print(client.outputs(job_id, "results"))
 The same installed package supports a terminal flow:
 
 ```sh
+gridline workload search workload.yaml
 gridline workload validate --file workload.yaml
 gridline workload plan --file workload.yaml
 gridline workload run --file workload.yaml --apply --max-cost-usd 5 \
@@ -81,6 +84,13 @@ approval; the Python CLI never stores a privileged refresh token.
 After revoking a token, remove its local file before running setup again; setup never
 overwrites an existing file.
 
+`plan()` validates YAML and checks advertised task readiness before reserving or
+uploading inputs. An explicitly unavailable managed ASR/LLM runtime, minimal managed
+model resolver, or custom finite path raises `GridlineError` with code
+`planning_unavailable`. Qualify the custom container and enable its launch path, or
+use available managed runtime/full YAML settings as indicated by the error. Missing
+task readiness fields on older servers preserve existing behavior. Custom endpoint
+support remains a server planning decision; finite readiness does not describe it.
 `plan()` stages input bytes but does not allocate a GPU. `launch()` never silently
 changes a plan or retries an ambiguous paid request. If launch outcome is unknown,
 inspect `LaunchOutcomeUnknown.workload_id` with the same idempotency key; do not use a
@@ -89,6 +99,16 @@ Cancellation requests stop; cleanup and final provider billing can remain pendin
 For finite jobs, `wait()` returns when outputs are complete, even if cleanup and billing
 leave `outcome` pending. Check `status()` later for final settlement.
 
+`search()` reads only YAML and connected-provider catalogs. It does not inspect or
+upload referenced inputs, resolve a model or image, create a workload, or allocate a
+GPU. `availability()["searchAvailable"]` is separate from planning and execution
+readiness. Missing price, VRAM, capacity, or topology facts remain unknown. Partial
+catalog coverage and unsupported execution remain visible; a search result is not a
+launch quote. `scopeStatus: "empty_scope"` with `catalogCompleteness: "not_applicable"`
+means no accounts were searched. Servers with catalog search disabled return a
+search availability error. The CLI prints the same JSON response and also accepts
+`gridline workload search --file workload.yaml`.
+
 When worker progress is enabled on the hosted API/control service and supported by the
 deployed worker image, `status()` also returns optional `progress`:
 

{gridlinegpu-0.1.4 → gridlinegpu-0.1.5}/README.md

@@ -29,6 +29,8 @@ may still cap inputs at 40 MiB and outputs at 8 MiB.
 from gridlinegpu import GridlineClient
 
 client = GridlineClient()
+search = client.search("workload.yaml")
+print(search["coverage"], search["offers"])  # Catalog facts may be unknown; coverage may be partial.
 plan = client.plan("workload.yaml")
 print(plan.review)  # Check selected GPU, exclusions, estimate, and maximum.
 
@@ -43,6 +45,7 @@ print(client.outputs(job_id, "results"))
 The same installed package supports a terminal flow:
 
 ```sh
+gridline workload search workload.yaml
 gridline workload validate --file workload.yaml
 gridline workload plan --file workload.yaml
 gridline workload run --file workload.yaml --apply --max-cost-usd 5 \
@@ -66,6 +69,13 @@ approval; the Python CLI never stores a privileged refresh token.
 After revoking a token, remove its local file before running setup again; setup never
 overwrites an existing file.
 
+`plan()` validates YAML and checks advertised task readiness before reserving or
+uploading inputs. An explicitly unavailable managed ASR/LLM runtime, minimal managed
+model resolver, or custom finite path raises `GridlineError` with code
+`planning_unavailable`. Qualify the custom container and enable its launch path, or
+use available managed runtime/full YAML settings as indicated by the error. Missing
+task readiness fields on older servers preserve existing behavior. Custom endpoint
+support remains a server planning decision; finite readiness does not describe it.
 `plan()` stages input bytes but does not allocate a GPU. `launch()` never silently
 changes a plan or retries an ambiguous paid request. If launch outcome is unknown,
 inspect `LaunchOutcomeUnknown.workload_id` with the same idempotency key; do not use a
@@ -74,6 +84,16 @@ Cancellation requests stop; cleanup and final provider billing can remain pendin
 For finite jobs, `wait()` returns when outputs are complete, even if cleanup and billing
 leave `outcome` pending. Check `status()` later for final settlement.
 
+`search()` reads only YAML and connected-provider catalogs. It does not inspect or
+upload referenced inputs, resolve a model or image, create a workload, or allocate a
+GPU. `availability()["searchAvailable"]` is separate from planning and execution
+readiness. Missing price, VRAM, capacity, or topology facts remain unknown. Partial
+catalog coverage and unsupported execution remain visible; a search result is not a
+launch quote. `scopeStatus: "empty_scope"` with `catalogCompleteness: "not_applicable"`
+means no accounts were searched. Servers with catalog search disabled return a
+search availability error. The CLI prints the same JSON response and also accepts
+`gridline workload search --file workload.yaml`.
+
 When worker progress is enabled on the hosted API/control service and supported by the
 deployed worker image, `status()` also returns optional `progress`:
 

{gridlinegpu-0.1.4 → gridlinegpu-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gridlinegpu"
-version = "0.1.4"
+version = "0.1.5"
 description = "Python client for Gridline YAML workload routing"
 readme = "README.md"
 requires-python = ">=3.10"

{gridlinegpu-0.1.4 → gridlinegpu-0.1.5}/src/gridlinegpu/cli.py

@@ -49,8 +49,11 @@ def _parser() -> argparse.ArgumentParser:
     revoke.add_argument("token_id")
     revoke.add_argument("--apply", action="store_true")
 
-    workload = commands.add_parser("workload", help="Validate, plan, launch, and inspect YAML jobs")
+    workload = commands.add_parser("workload", help="Search catalogs, plan, launch, and inspect YAML jobs")
     actions = workload.add_subparsers(dest="action", required=True)
+    search = actions.add_parser("search", help="Search connected-provider catalogs without staging inputs")
+    search.add_argument("yaml_path", type=Path, nargs="?")
+    search.add_argument("--file", type=Path)
     for name, help_text in [
         ("validate", "Validate YAML without allocating a GPU"),
         ("plan", "Stage inputs and review a route without allocating a GPU"),
@@ -77,7 +80,7 @@ def _parser() -> argparse.ArgumentParser:
         if name == "cancel":
             action.add_argument("--apply", action="store_true")
             action.add_argument("--yes", action="store_true")
-    actions.add_parser("availability", help="Show account planning and execution gates")
+    actions.add_parser("availability", help="Show account search, planning, and execution gates")
     return parser
 
 
@@ -145,6 +148,10 @@ def main(argv: Sequence[str] | None = None, *, input_stream: TextIO = sys.stdin,
         action = args.action
         if action == "availability":
             result = client.availability()
+        elif action == "search":
+            if (args.yaml_path is None) == (args.file is None):
+                raise ValueError("workload search requires YAML or --file YAML, exactly once")
+            result = client.search(args.yaml_path or args.file)
         elif action == "validate":
             result = client.validate(args.file)
         elif action == "plan":

{gridlinegpu-0.1.4 → gridlinegpu-0.1.5}/src/gridlinegpu/client.py

@@ -100,21 +100,43 @@ class GridlineClient:
     def availability(self) -> dict[str, Any]:
         return self._json("GET", f"{_API}/availability")
 
+    def search(self, yaml_path: str | Path) -> dict[str, Any]:
+        """Read connected-provider catalogs without staging inputs or creating a workload.
+
+        Nullable facts and partial coverage remain visible in the returned search.
+        Search availability is independent of planning and execution readiness.
+        """
+        _, source, _ = _read_yaml(yaml_path)
+        result = self._json("POST", f"{_API}/search", {"schemaVersion": 1, "yaml": source})
+        if (result.get("schemaVersion") != 1
+                or result.get("scopeStatus") not in ("empty_scope", "queried")
+                or result.get("catalogCompleteness") not in ("complete", "partial", "not_applicable")
+                or not isinstance(result.get("observedAt"), str)
+                or not isinstance(result.get("intent"), dict)
+                or not isinstance(result.get("coverage"), list)
+                or not isinstance(result.get("offers"), list)):
+            raise GridlineError("Invalid catalog search response", code="remote_contract_invalid")
+        return result
+
     def validate(self, yaml_path: str | Path) -> dict[str, Any]:
         _, source, _ = _read_yaml(yaml_path)
         return self._json(
             "POST", f"{_API}/validate", {"schemaVersion": 1, "yaml": source, "attachmentBindings": []}
         )
 
-    def plan(self, yaml_path: str | Path, *, submission_key: str | None = None) -> PlannedWorkload:
+    def plan(self, yaml_path: str | Path, *, submission_key: str | None = None,
+             qualification_timeout: float = 3600) -> PlannedWorkload:
         """Create a fresh submission; reuse submission_key only to retry an uncertain submit."""
         if submission_key is not None and not _KEY.fullmatch(submission_key):
             raise ValueError("submission_key must contain 1–128 safe characters")
+        if not isinstance(qualification_timeout, (int, float)) or isinstance(qualification_timeout, bool) or not 0 <= qualification_timeout <= 3600:
+            raise ValueError("qualification_timeout must be between 0 and 3600 seconds")
         path, source, document = _read_yaml(yaml_path)
         validated = self.validate(path)
         available = self.availability()
         if not available.get("planningAvailable"):
             raise GridlineError("YAML planning is unavailable for this account", code="planning_unavailable")
+        _require_task_planning(document, available)
         inputs = _local_inputs(document)
         required = validated.get("requiredAttachments")
         names = [name for name, _ in inputs]
@@ -135,7 +157,21 @@ class GridlineClient:
             "POST", f"{_API}/submit", body, key=submission_key or f"sdk-submit-{uuid.uuid4()}"
         )
         workload_id = _id(submitted.get("workloadId"), "workloadId")
-        result = self._json("POST", f"{_API}/{quote(workload_id)}/plan")
+        deadline = time.monotonic() + qualification_timeout
+        while True:
+            try:
+                result = self._json("POST", f"{_API}/{quote(workload_id)}/plan")
+                break
+            except GridlineError as error:
+                if error.code != "image_qualification_pending" or error.status != 409:
+                    raise
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise GridlineError(
+                        f"Image qualification still pending for workload {workload_id}; retry planning later.",
+                        code="image_qualification_pending", status=409,
+                    ) from error
+                time.sleep(min(15, remaining))
         if result.get("workloadId") != workload_id or result.get("workloadHash") != submitted.get("workloadHash"):
             raise GridlineError("Plan identity differs from submitted workload", code="remote_contract_invalid")
         return PlannedWorkload(path, _sha(source.encode()), workload_id, result)
@@ -536,6 +572,41 @@ def _read_yaml(value: str | Path) -> tuple[Path, str, dict[str, Any]]:
     return path, source, document
 
 
+def _require_task_planning(document: dict[str, Any], available: dict[str, Any]) -> None:
+    """Honor explicit readiness limits after server syntax validation, before staging."""
+    task = document.get("task")
+    if not isinstance(task, dict):
+        return
+    minimal = "apiVersion" not in document
+    kind = task.get("kind") if not minimal else ("custom" if "class" in task else "managed")
+    if kind == "managed":
+        flag = {
+            "asr_transcription": "managedAsrPlanningAvailable",
+            "llm_inference": "managedLlmPlanningAvailable",
+        }.get(task.get("operation"))
+        if flag and available.get(flag) is False:
+            raise GridlineError(
+                f"Planning for {task['operation']} is unavailable for this account; "
+                "enable a supported managed runtime before staging inputs",
+                code="planning_unavailable",
+            )
+        if minimal and available.get("minimalManagedResolutionAvailable") is False:
+            raise GridlineError(
+                "Minimal managed YAML resolution is unavailable; use full workload YAML "
+                "with explicit runtime settings or enable managed model resolution",
+                code="planning_unavailable",
+            )
+    elif kind == "custom":
+        execution = document.get("execution", {"mode": "finite"} if minimal else {})
+        if (isinstance(execution, dict) and execution.get("mode", "finite" if minimal else None) == "finite"
+                and available.get("customFinitePlanningAvailable") is False):
+            raise GridlineError(
+                "Custom finite workload planning is unavailable for this account; "
+                "complete container qualification and enable custom launch planning before staging inputs",
+                code="planning_unavailable",
+            )
+
+
 def _local_inputs(document: dict[str, Any]) -> list[tuple[str, dict[str, Any]]]:
     if "apiVersion" in document:
         inputs = document.get("inputs", [])

{gridlinegpu-0.1.4 → gridlinegpu-0.1.5}/src/gridlinegpu.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridlinegpu
-Version: 0.1.4
+Version: 0.1.5
 Summary: Python client for Gridline YAML workload routing
 Author: Gridline GPU
 License: Proprietary
@@ -44,6 +44,8 @@ may still cap inputs at 40 MiB and outputs at 8 MiB.
 from gridlinegpu import GridlineClient
 
 client = GridlineClient()
+search = client.search("workload.yaml")
+print(search["coverage"], search["offers"])  # Catalog facts may be unknown; coverage may be partial.
 plan = client.plan("workload.yaml")
 print(plan.review)  # Check selected GPU, exclusions, estimate, and maximum.
 
@@ -58,6 +60,7 @@ print(client.outputs(job_id, "results"))
 The same installed package supports a terminal flow:
 
 ```sh
+gridline workload search workload.yaml
 gridline workload validate --file workload.yaml
 gridline workload plan --file workload.yaml
 gridline workload run --file workload.yaml --apply --max-cost-usd 5 \
@@ -81,6 +84,13 @@ approval; the Python CLI never stores a privileged refresh token.
 After revoking a token, remove its local file before running setup again; setup never
 overwrites an existing file.
 
+`plan()` validates YAML and checks advertised task readiness before reserving or
+uploading inputs. An explicitly unavailable managed ASR/LLM runtime, minimal managed
+model resolver, or custom finite path raises `GridlineError` with code
+`planning_unavailable`. Qualify the custom container and enable its launch path, or
+use available managed runtime/full YAML settings as indicated by the error. Missing
+task readiness fields on older servers preserve existing behavior. Custom endpoint
+support remains a server planning decision; finite readiness does not describe it.
 `plan()` stages input bytes but does not allocate a GPU. `launch()` never silently
 changes a plan or retries an ambiguous paid request. If launch outcome is unknown,
 inspect `LaunchOutcomeUnknown.workload_id` with the same idempotency key; do not use a
@@ -89,6 +99,16 @@ Cancellation requests stop; cleanup and final provider billing can remain pendin
 For finite jobs, `wait()` returns when outputs are complete, even if cleanup and billing
 leave `outcome` pending. Check `status()` later for final settlement.
 
+`search()` reads only YAML and connected-provider catalogs. It does not inspect or
+upload referenced inputs, resolve a model or image, create a workload, or allocate a
+GPU. `availability()["searchAvailable"]` is separate from planning and execution
+readiness. Missing price, VRAM, capacity, or topology facts remain unknown. Partial
+catalog coverage and unsupported execution remain visible; a search result is not a
+launch quote. `scopeStatus: "empty_scope"` with `catalogCompleteness: "not_applicable"`
+means no accounts were searched. Servers with catalog search disabled return a
+search availability error. The CLI prints the same JSON response and also accepts
+`gridline workload search --file workload.yaml`.
+
 When worker progress is enabled on the hosted API/control service and supported by the
 deployed worker image, `status()` also returns optional `progress`:
 

{gridlinegpu-0.1.4 → gridlinegpu-0.1.5}/tests/test_cli.py

@@ -1,4 +1,5 @@
 import io
+import json
 import unittest
 from unittest.mock import MagicMock, patch
 
@@ -14,6 +15,35 @@ class CliTest(unittest.TestCase):
     def invoke(self, *arguments):
         return main(arguments, input_stream=self.input, output=self.output, errors=self.errors)
 
+    @patch("gridlinegpu.cli.GridlineClient")
+    def test_search_accepts_positional_yaml_and_prints_coverage_and_unknown_facts(self, client_type):
+        result = {"scopeStatus": "queried", "catalogCompleteness": "partial",
+                  "coverage": [{"provider": "lambda", "status": "failed"}],
+                  "offers": [{"provider": "runpod", "pricePerHr": None,
+                              "unknownFacts": ["pricePerHr"]}]}
+        client_type.return_value.search.return_value = result
+        self.assertEqual(self.invoke("workload", "search", "workload.yaml"), 0)
+        self.assertEqual(json.loads(self.output.getvalue()), result)
+        self.assertEqual(str(client_type.return_value.search.call_args.args[0]), "workload.yaml")
+        client_type.return_value.plan.assert_not_called()
+        client_type.return_value.validate.assert_not_called()
+        client_type.return_value.availability.assert_not_called()
+        client_type.return_value.launch.assert_not_called()
+
+    @patch("gridlinegpu.cli.GridlineClient")
+    def test_search_accepts_file_option_without_mutation_confirmation(self, client_type):
+        client_type.return_value.search.return_value = {"scopeStatus": "empty_scope", "offers": []}
+        self.assertEqual(self.invoke("workload", "search", "--file", "workload.yaml"), 0)
+        client_type.return_value.search.assert_called_once()
+        self.assertEqual(self.errors.getvalue(), "")
+
+    @patch("gridlinegpu.cli.GridlineClient")
+    def test_search_rejects_missing_or_duplicate_source(self, client_type):
+        for arguments in (("workload", "search"),
+                          ("workload", "search", "one.yaml", "--file", "two.yaml")):
+            self.assertEqual(self.invoke(*arguments), 1)
+        client_type.return_value.search.assert_not_called()
+
     @patch("gridlinegpu.cli.GridlineClient")
     def test_paid_run_requires_apply_and_does_not_plan(self, client_type):
         code = self.invoke("workload", "run", "--file", "workload.yaml",

{gridlinegpu-0.1.4 → gridlinegpu-0.1.5}/tests/test_client.py

@@ -13,6 +13,22 @@ from gridlinegpu import GridlineClient, GridlineError
 
 
 TOKEN = "gla_" + "a" * 43
+SEARCH = {
+    "schemaVersion": 1,
+    "intent": {"providers": {"mode": "all_connected"}, "gpuCount": {"minimum": 1, "maximum": 128},
+               "minimumVramGb": None, "minimumDiskGb": None, "blockedCountries": [],
+               "allowedCountries": [], "allowedRegions": []},
+    "scopeStatus": "queried",
+    "catalogCompleteness": "partial",
+    "observedAt": "2026-10-01T00:00:00.000Z",
+    "coverage": [{"provider": "lambda", "accountRef": "account_opaque", "status": "partial",
+                  "complete": False, "reason": "offer_limit", "observedOffers": 1}],
+    "offers": [{"provider": "lambda", "accountRef": "account_opaque", "offerId": "offer_opaque",
+                "gpuModel": "future-gpu", "gpuCount": 2, "vramGb": None, "vcpu": None,
+                "ramGb": None, "diskGb": None, "pricePerHr": None, "priceBasis": "unknown",
+                "region": None, "countryCode": None, "availability": "unknown",
+                "executionEligibility": "unknown", "unknownFacts": ["vramGb", "pricePerHr"]}],
+}
 YAML = """name: speech
 task:
   operation: asr_transcription
@@ -52,6 +68,32 @@ geography: { allowedCountries: [], blockedCountries: [], allowedRegions: [] }
 retry: { maximumAttempts: 1, interruption: forbid, spot: forbid }
 profiling: { allowed: false }
 """
+FULL_MANAGED_YAML = CUSTOM_YAML[:CUSTOM_YAML.index("task:\n")] + """task:
+  kind: managed
+  operation: asr_transcription
+  model: { id: example/model }
+  engine: { selection: fixed, name: fixture-engine }
+  allowedPrecisions: [float16]
+  allowedQuantizations: [native]
+  settings: {}
+""" + CUSTOM_YAML[CUSTOM_YAML.index("execution:"):]
+MINIMAL_CUSTOM_YAML = """task:
+  class: batch
+  image: example/worker@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+  command: [python, run.py]
+  runtime: { architecture: amd64, internet: required }
+inputs:
+  audio: { file: audio.wav, format: wav }
+outputs:
+  result: { path: result.json, format: json }
+limits: { maxCostUSD: 5, deadline: 1h }
+resources:
+  gpu: { count: { min: 1, max: 1 }, vramMin: 24GB, topology: [single], vendors: [nvidia] }
+  cpuMin: 2
+  memoryMin: 4GB
+  diskMin: 20GB
+  estimatedDuration: 1m
+"""
 
 
 class Response(io.BytesIO):
@@ -81,6 +123,8 @@ class FakeOpener:
         self.tus_fail_final_reply_and_head = False
         self.tus_patches = []
         self.maximum_attachment_bytes = 1024
+        self.planning_readiness = {}
+        self.search_result = SEARCH
         self.required_attachments = ["audio"]
         self.job = {"jobId": "job_1", "outcome": "succeeded"}
         self.expiry = (datetime.now(timezone.utc) + timedelta(minutes=2)).isoformat()
@@ -88,12 +132,15 @@ class FakeOpener:
     def open(self, request, timeout):
         path = request.full_url.removeprefix("https://gridlinegpu.com")
         self.calls.append((request.get_method(), path, request.headers, request.data))
-        if path == "/api/workloads/yaml/validate":
+        if path == "/api/workloads/yaml/search":
+            result = self.search_result
+        elif path == "/api/workloads/yaml/validate":
             result = {"schemaVersion": 1, "requiredAttachments": self.required_attachments}
         elif path == "/api/workloads/yaml/availability":
             result = {"schemaVersion": 1, "planningAvailable": True, "executionEnabled": True,
                       "artifactStagingAvailable": True,
-                      "maximumAttachmentBytes": self.maximum_attachment_bytes}
+                      "maximumAttachmentBytes": self.maximum_attachment_bytes,
+                      **self.planning_readiness}
         elif path == "/api/workloads/yaml/attachments":
             requested = json.loads(request.data)
             upload = ({"method": "TUS",
@@ -180,6 +227,44 @@ class ClientTest(unittest.TestCase):
         self.opener.output_digest = hashlib.sha256(b"{}").hexdigest()
         self.client = GridlineClient(token=TOKEN, opener=self.opener)
 
+    def test_search_reads_only_yaml_with_unpinned_runtime_and_missing_input(self):
+        for source in (YAML, MINIMAL_CUSTOM_YAML.replace(
+                "example/worker@sha256:" + "a" * 64, "example/worker:latest")):
+            with self.subTest(source=source.splitlines()[0]):
+                self.path.write_text(source)
+                self.opener.calls.clear()
+                (self.path.parent / "audio.wav").unlink(missing_ok=True)
+                self.opener.planning_readiness = {"planningAvailable": False,
+                                                 "executionEnabled": False,
+                                                 "artifactStagingAvailable": False}
+                with patch("gridlinegpu.client._local_inputs") as inputs, patch(
+                        "gridlinegpu.client._bounded_file_identity") as identity:
+                    result = self.client.search(self.path)
+                inputs.assert_not_called()
+                identity.assert_not_called()
+                self.assertEqual(result, SEARCH)
+                self.assertIsNone(result["offers"][0]["pricePerHr"])
+                self.assertEqual(len(self.opener.calls), 1)
+                method, path, headers, body = self.opener.calls[0]
+                self.assertEqual((method, path), ("POST", "/api/workloads/yaml/search"))
+                self.assertEqual(json.loads(body), {"schemaVersion": 1, "yaml": source})
+                self.assertNotIn("Idempotency-key", headers)
+                self.assertEqual(self.opener.uploaded, b"")
+
+    def test_search_empty_scope_is_not_catalog_success(self):
+        self.opener.search_result = {**SEARCH, "scopeStatus": "empty_scope",
+                                    "catalogCompleteness": "not_applicable", "coverage": [], "offers": []}
+        result = self.client.search(self.path)
+        self.assertEqual(result["scopeStatus"], "empty_scope")
+        self.assertEqual(result["catalogCompleteness"], "not_applicable")
+        self.assertEqual(result["offers"], [])
+
+    def test_search_rejects_unknown_response_version(self):
+        self.opener.search_result = {**SEARCH, "schemaVersion": 2}
+        with self.assertRaises(GridlineError) as raised:
+            self.client.search(self.path)
+        self.assertEqual(raised.exception.code, "remote_contract_invalid")
+
     def test_plan_launch_and_verified_download(self):
         plan = self.client.plan(self.path)
         self.assertEqual(plan.workload_id, "yaml_1")
@@ -191,6 +276,131 @@ class ClientTest(unittest.TestCase):
         self.assertEqual(Path(saved["downloaded"][0]["path"]).read_bytes(), b"{}")
         self.assertRaises(FileExistsError, self.client.outputs, "job_1", Path(self.folder.name) / "results")
 
+    def test_unavailable_custom_finite_planning_stops_before_inputs_and_submission(self):
+        for source in (CUSTOM_YAML, MINIMAL_CUSTOM_YAML,
+                       MINIMAL_CUSTOM_YAML + "execution: { mode: finite }\n"):
+            with self.subTest(source=source.splitlines()[0]):
+                self.path.write_text(source)
+                self.opener.calls.clear()
+                self.opener.upload_required = True
+                self.opener.planning_readiness = {"customFinitePlanningAvailable": False}
+                with patch("gridlinegpu.client._bounded_file_identity") as identity:
+                    with self.assertRaisesRegex(GridlineError, "container qualification") as raised:
+                        self.client.plan(self.path)
+                self.assertEqual(raised.exception.code, "planning_unavailable")
+                identity.assert_not_called()
+                self.assertEqual([path for _, path, _, _ in self.opener.calls],
+                                 ["/api/workloads/yaml/validate", "/api/workloads/yaml/availability"])
+                self.assertEqual(self.opener.uploaded, b"")
+
+    def test_unavailable_managed_planning_stops_both_yaml_shapes_before_staging(self):
+        for operation, flag in (("asr_transcription", "managedAsrPlanningAvailable"),
+                                ("llm_inference", "managedLlmPlanningAvailable")):
+            full = FULL_MANAGED_YAML.replace("asr_transcription", operation)
+            for source in (YAML.replace("asr_transcription", operation), full):
+                with self.subTest(operation=operation, full=source.startswith("apiVersion")):
+                    self.path.write_text(source)
+                    self.opener.calls.clear()
+                    self.opener.planning_readiness = {flag: False}
+                    self.opener.upload_required = True
+                    with self.assertRaisesRegex(GridlineError, operation) as raised:
+                        self.client.plan(self.path)
+                    self.assertEqual(raised.exception.code, "planning_unavailable")
+                    self.assertEqual([path for _, path, _, _ in self.opener.calls],
+                                     ["/api/workloads/yaml/validate", "/api/workloads/yaml/availability"])
+                    self.assertEqual(self.opener.uploaded, b"")
+
+    def test_unavailable_minimal_managed_resolution_stops_before_staging(self):
+        self.opener.planning_readiness = {"managedAsrPlanningAvailable": True,
+                                         "minimalManagedResolutionAvailable": False}
+        with self.assertRaisesRegex(GridlineError, "full workload YAML") as raised:
+            self.client.plan(self.path)
+        self.assertEqual(raised.exception.code, "planning_unavailable")
+        self.assertEqual([path for _, path, _, _ in self.opener.calls],
+                         ["/api/workloads/yaml/validate", "/api/workloads/yaml/availability"])
+
+    def test_ready_tasks_stage_and_plan_without_using_unrelated_readiness_flags(self):
+        for source, readiness in (
+            (YAML, {"managedAsrPlanningAvailable": True, "managedLlmPlanningAvailable": False,
+                    "minimalManagedResolutionAvailable": True, "customFinitePlanningAvailable": False}),
+            (YAML.replace("asr_transcription", "llm_inference"),
+             {"managedAsrPlanningAvailable": False, "managedLlmPlanningAvailable": True,
+              "minimalManagedResolutionAvailable": True, "customFinitePlanningAvailable": False}),
+            (MINIMAL_CUSTOM_YAML, {"managedAsrPlanningAvailable": False,
+                                  "managedLlmPlanningAvailable": False,
+                                  "minimalManagedResolutionAvailable": False,
+                                  "customFinitePlanningAvailable": True}),
+            (CUSTOM_YAML, {"customFinitePlanningAvailable": True}),
+            (FULL_MANAGED_YAML, {"managedAsrPlanningAvailable": True,
+                                 "minimalManagedResolutionAvailable": False}),
+            (FULL_MANAGED_YAML.replace("asr_transcription", "llm_inference"),
+             {"managedLlmPlanningAvailable": True, "minimalManagedResolutionAvailable": False}),
+        ):
+            with self.subTest(readiness=readiness):
+                self.path.write_text(source)
+                self.opener.calls.clear()
+                self.opener.planning_readiness = readiness
+                self.opener.upload_required = True
+                full = source.startswith("apiVersion")
+                self.opener.required_attachments = ["alpha", "beta"] if full else ["audio"]
+                for name in ("alpha", "beta"):
+                    (Path(self.folder.name) / f"{name}.bin").write_bytes(b"RIFF")
+                planned = self.client.plan(self.path)
+                self.assertIsNotNone(planned.quote)
+                self.assertEqual(self.opener.uploaded, b"RIFF")
+                self.assertTrue(any(path.endswith("/submit") for _, path, _, _ in self.opener.calls))
+
+    def test_custom_endpoint_does_not_use_finite_readiness(self):
+        self.path.write_text(MINIMAL_CUSTOM_YAML.replace(
+            "  result: { path: result.json, format: json }",
+            "  api: { endpoint: http, port: 8080, healthPath: /health }",
+        ) + """execution:
+  mode: endpoint
+  maxLifetime: 1h
+  maxRequests: 10
+  maxConcurrency: 1
+  startupDeadline: 5m
+  idleTimeout: 10m
+""")
+        self.opener.planning_readiness = {"customFinitePlanningAvailable": False,
+                                         "minimalManagedResolutionAvailable": False}
+        self.assertIsNotNone(self.client.plan(self.path).quote)
+
+    def test_legacy_availability_without_task_fields_still_stages_and_plans(self):
+        self.path.write_text(MINIMAL_CUSTOM_YAML)
+        self.opener.upload_required = True
+        self.assertIsNotNone(self.client.plan(self.path).quote)
+        self.assertEqual(self.opener.uploaded, b"RIFF")
+
+    def test_server_validation_error_is_preserved_before_readiness_or_staging(self):
+        self.opener.planning_readiness = {"customFinitePlanningAvailable": False}
+        error = GridlineError("Invalid workload", code="invalid_workload")
+        with patch.object(self.client, "validate", side_effect=error):
+            with self.assertRaises(GridlineError) as raised:
+                self.client.plan(self.path)
+        self.assertIs(raised.exception, error)
+        self.assertEqual(self.opener.calls, [])
+    def test_qualification_wait_reuses_submission_and_only_retries_pending_plan(self):
+        original = self.client._json
+        calls = []
+        def pending_once(method, path, *args, **kwargs):
+            if path.endswith("/plan"):
+                calls.append(path)
+                if len(calls) == 1:
+                    raise GridlineError("pending", code="image_qualification_pending", status=409)
+            return original(method, path, *args, **kwargs)
+        with patch.object(self.client, "_json", side_effect=pending_once), patch("gridlinegpu.client.time.sleep") as wait:
+            self.assertEqual(self.client.plan(self.path).workload_id, "yaml_1")
+        self.assertEqual(calls, ["/api/workloads/yaml/yaml_1/plan"] * 2)
+        wait.assert_called_once_with(15)
+        self.assertEqual(sum(path.endswith("/submit") for _, path, _, _ in self.opener.calls), 1)
+        for code in ("image_qualification_pending", "image_qualification_failed"):
+            with patch.object(self.client, "_json", side_effect=lambda method, path, *args, **kwargs:
+                              (_ for _ in ()).throw(GridlineError("pending", code=code, status=409)) if path.endswith("/plan") else original(method, path, *args, **kwargs)), patch("gridlinegpu.client.time.sleep") as wait:
+                with self.assertRaises(GridlineError):
+                    self.client.plan(self.path, qualification_timeout=0)
+                wait.assert_not_called()
+
     def test_minimal_file_extension_supplies_omitted_upload_format(self):
         (Path(self.folder.name) / "talk.OGG").write_bytes(b"OggS")
         self.path.write_text("""task:
@@ -253,7 +463,7 @@ limits: { maxCostUSD: 5 }
         digest = hashlib.sha256(b"RIFF").hexdigest()
         with patch("gridlinegpu.client._bounded_file_identity", return_value=(4, digest)) as identity:
             self.client.plan(self.path)
-        identity.assert_called_once_with(Path(self.folder.name) / "audio.wav",
+        identity.assert_called_once_with((Path(self.folder.name) / "audio.wav").resolve(),
                                          self.opener.maximum_attachment_bytes)
 
     def test_signed_tus_upload_streams_fixed_chunks_and_recovers_lost_patch_reply(self):