@honua/react 0.1.4-beta.0 → 0.1.9-beta.0

package/core/ogc-processes.js

@@ -23,10 +23,9 @@
  *
  * @module
  */
-import { HonuaJobPollTimeoutError, isJobTerminal } from "../contract/jobs.js";
-import { HonuaSdkError } from "./error-envelope.js";
+import { isJobTerminal } from "../contract/jobs.js";
 import { HonuaCapabilityNotSupportedError } from "./errors.js";
-import { hasOgcConformanceClass } from "./ogc-conformance.js";
+import { JobRunLifecycle } from "./job-run-lifecycle.js";
 import { createOgcMetadataParams, mergeHeaders } from "./wire-shared.js";
 const DEFAULT_POLL_INTERVAL_MS = 1_000;
 /**
@@ -35,7 +34,6 @@ const DEFAULT_POLL_INTERVAL_MS = 1_000;
  * never reaches a terminal state must not poll forever. Callers who genuinely
  * want a longer wait pass their own `deadlineMs`.
  */
-const DEFAULT_POLL_DEADLINE_MS = 600_000;
 /** Honua facade path prefix for OGC API Processes. */
 const PROCESSES_FACADE_BASE = "/ogc/processes";
 /**
@@ -49,7 +47,11 @@ const PROCESSES_CONFORMANCE = {
     core: "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/core",
     dismiss: "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/dismiss",
 };
-/** Substring matchers tolerant of OGC re-issuing the class URIs under a new part number. */
+/**
+ * Suffix matchers tolerant of a server publishing the class under a different
+ * host or path prefix, but *not* of a different class that merely starts with
+ * one of these. See {@link declaresConformanceClass}.
+ */
 const PROCESSES_CONFORMANCE_MATCH = {
     core: "processes-1/1.0/conf/core",
     dismiss: "processes-1/1.0/conf/dismiss",
@@ -77,6 +79,36 @@ const JOB_CONTROL = {
 function capabilityRefusal(capability, sourceId, context) {
     return new HonuaCapabilityNotSupportedError(capability, "ogc-processes", sourceId, { context });
 }
+/**
+ * `true` when the server declares exactly the named conformance class.
+ *
+ * The public `hasOgcConformanceClass()` is a documented *substring* test, which
+ * is the right tool for a caller probing an extension they already recognise.
+ * It is the wrong tool for a fail-closed gate: an unrecognised class that
+ * happens to extend one of ours — `…/conf/dismiss-disabled`, `…/conf/core-lite`,
+ * or a vendor class carrying the URI in a query string — would widen what the
+ * client is willing to send. So the gate anchors the match at the end of the
+ * class URI (ignoring a trailing slash, query, or fragment): a prefix the
+ * server chose is still tolerated, an unknown longer class is not.
+ */
+function declaresConformanceClass(conformance, classSuffix) {
+    for (const uri of conformance?.conformsTo ?? []) {
+        if (typeof uri !== "string")
+            continue;
+        const withoutFragment = uri.split("#")[0] ?? "";
+        let path = withoutFragment.split("?")[0] ?? "";
+        // Trailing slashes are trimmed by scanning, not by a `/+$/` regex: this
+        // string is server input, and that pattern backtracks on a URI made of
+        // many slashes.
+        let end = path.length;
+        while (end > 0 && path.charCodeAt(end - 1) === 47)
+            end -= 1;
+        path = path.slice(0, end);
+        if (path.endsWith(classSuffix))
+            return true;
+    }
+    return false;
+}
 /** `true` when the declaration list contains `option` (case-insensitive). */
 function declares(options, option) {
     if (!options)
@@ -226,9 +258,12 @@ export class HonuaOgcProcesses {
     declaredConformance;
     conformancePromise;
     /**
-     * `jobControlOptions` learned from `describe()` calls made through this
-     * handle. Callers that follow the natural discover → describe → execute flow
-     * therefore get process-level gating for free, with no extra round trip.
+     * `jobControlOptions` learned from `describe()` / `list()` calls made through
+     * this handle. Callers that follow the natural discover → describe → execute
+     * flow therefore get process-level gating for free, with no extra round trip.
+     *
+     * Each entry remembers which source taught it, because a later listing must
+     * not be able to downgrade what a description already established.
      */
     jobControlByProcess = new Map();
     constructor(options) {
@@ -253,19 +288,36 @@ export class HonuaOgcProcesses {
     async list(request = {}) {
         const response = await this.client.listOgcProcesses(this.withBase(request));
         for (const process of response?.processes ?? []) {
-            if (process?.id && process.jobControlOptions) {
-                this.jobControlByProcess.set(process.id, [...process.jobControlOptions]);
-            }
+            // A summary that omits `jobControlOptions` advertises no execution mode;
+            // recorded as an empty declaration so the mode gate refuses rather than
+            // reading silence as consent — but only where nothing better is known.
+            if (process?.id)
+                this.rememberJobControl(process.id, process.jobControlOptions, "summary");
         }
         return response;
     }
     async describe(processId, request = {}) {
         const description = await this.client.getOgcProcess(this.withBase({ ...request, processId }));
-        if (description?.jobControlOptions) {
-            this.jobControlByProcess.set(processId, [...description.jobControlOptions]);
-        }
+        // As in `list()`: an omitted `jobControlOptions` is an empty declaration.
+        // A description is the authoritative source, so this always wins.
+        this.rememberJobControl(processId, description?.jobControlOptions, "description");
         return description;
     }
+    /**
+     * Record what a process advertises, keeping the more authoritative source.
+     *
+     * Silence is still not consent — an omitted `jobControlOptions` is stored as
+     * an empty declaration, and an explicit mode against it is refused. But a
+     * process summary may legally omit what the full description declares, so a
+     * `list()` refresh after a `describe()` must not overwrite the description's
+     * answer with the listing's silence. Refusing an execution the server did
+     * declare is as wrong as permitting one it did not.
+     */
+    rememberJobControl(processId, options, source) {
+        if (source === "summary" && this.jobControlByProcess.get(processId)?.source === "description")
+            return;
+        this.jobControlByProcess.set(processId, { options: [...(options ?? [])], source });
+    }
     /**
      * Submit a process for execution and return an `IJobRun` — always, so the
      * caller reads results through one surface whichever Core response shape the
@@ -289,7 +341,7 @@ export class HonuaOgcProcesses {
         const conformance = await this.assertExecutionDeclared(request);
         const accepted = await this.client.executeOgcProcess(executeRequest);
         const processId = accepted.processID ?? request.processId;
-        const jobControlOptions = request.jobControlOptions ?? this.jobControlByProcess.get(request.processId);
+        const jobControlOptions = request.jobControlOptions ?? this.jobControlByProcess.get(request.processId)?.options;
         if (accepted.synchronous === true) {
             // Core assigns no job identifier to a synchronous execution; the results
             // document is already in hand, so the run starts terminal.
@@ -317,7 +369,7 @@ export class HonuaOgcProcesses {
     /** Adopt an existing job by id (useful when reconnecting after navigation). */
     job(jobId, options = {}) {
         const { basePath } = this.withBase(options);
-        const jobControlOptions = options.processId ? this.jobControlByProcess.get(options.processId) : undefined;
+        const jobControlOptions = options.processId ? this.jobControlByProcess.get(options.processId)?.options : undefined;
         return new HonuaOgcProcessJobRun({
             client: this.client,
             jobId,
@@ -364,7 +416,11 @@ export class HonuaOgcProcesses {
      */
     async assertExecutionDeclared(request) {
         const conformance = await this.resolveConformance(request.signal);
-        if (conformance?.conformsTo && !hasOgcConformanceClass(conformance, PROCESSES_CONFORMANCE_MATCH.core)) {
+        // Under `"strict"` the declaration was fetched, so silence is an answer:
+        // a document that declares no Core class — or none at all — refuses. Under
+        // `"advertised"` only a declaration actually in hand can refuse.
+        const declarationInHand = conformance?.conformsTo !== undefined || this.capabilityPolicy === "strict";
+        if (declarationInHand && !declaresConformanceClass(conformance, PROCESSES_CONFORMANCE_MATCH.core)) {
             throw capabilityRefusal("processes.execute", request.processId, {
                 missingClass: PROCESSES_CONFORMANCE.core,
                 construct: "execute",
@@ -375,11 +431,15 @@ export class HonuaOgcProcesses {
         // shapes land on the same `IJobRun`. Only an explicit preference is gated.
         if (mode === "auto")
             return conformance;
-        let jobControlOptions = request.jobControlOptions ?? this.jobControlByProcess.get(request.processId);
+        let jobControlOptions = request.jobControlOptions ?? this.jobControlByProcess.get(request.processId)?.options;
         if (!jobControlOptions && this.capabilityPolicy === "strict") {
             const description = await this.describe(request.processId, request.signal ? { signal: request.signal } : {});
-            jobControlOptions = description.jobControlOptions;
+            // An omitted `jobControlOptions` is an empty declaration, never a wildcard:
+            // the server was asked and advertised no execution mode at all.
+            jobControlOptions = description.jobControlOptions ?? [];
         }
+        // Only a process this handle has never seen described is unknown; every
+        // observed description contributes a declaration, empty or otherwise.
         if (!jobControlOptions)
             return conformance;
         const required = mode === "sync" ? JOB_CONTROL.sync : JOB_CONTROL.async;
@@ -413,11 +473,7 @@ export class HonuaOgcProcessJobRun {
     /** Server-advertised routes, refreshed from every `links[]` the job reports. */
     statusPath;
     resultsPath;
-    currentStatus;
-    currentProgress;
-    terminalSnapshot;
-    terminalPromise;
-    listeners = new Set();
+    lifecycle;
     constructor(options) {
         this.client = options.client;
         this.id = options.jobId;
@@ -433,8 +489,14 @@ export class HonuaOgcProcessJobRun {
         this.pollFn = options.pollFn ?? ((jobId, signal) => this.fetchStatus(jobId, signal));
         const initial = options.initialStatus;
         this.absorbLinks(initial?.links);
-        this.currentStatus = initial?.status ?? "accepted";
-        this.currentProgress = progressFromOgcStatus(initial);
+        this.lifecycle = new JobRunLifecycle({
+            id: this.id,
+            initialStatus: initial?.status ?? "accepted",
+            initialProgress: progressFromOgcStatus(initial),
+            pollIntervalMs: () => this.pollIntervalMs,
+            pollBudget: this.pollBudget,
+            poll: async (signal) => this.translateOgcStatus(await this.pollFn(this.id, signal)),
+        });
     }
     async fetchStatus(jobId, signal) {
         if (this.capabilityPolicy === "strict" && this.statusPath === undefined) {
@@ -470,57 +532,32 @@ export class HonuaOgcProcessJobRun {
         }
     }
     get status() {
-        return this.currentStatus;
+        return this.lifecycle.status;
     }
     get progress() {
-        return this.currentProgress;
+        return this.lifecycle.progress;
     }
     async poll() {
-        if (this.terminalSnapshot) {
-            return this.terminalSnapshot;
-        }
-        const ogcStatus = await this.pollFn(this.id);
-        return this.handleOgcStatus(ogcStatus);
+        return this.lifecycle.poll();
     }
     watch(listener) {
-        this.listeners.add(listener);
-        return () => this.listeners.delete(listener);
+        return this.lifecycle.watch(listener);
     }
     async results(options = {}) {
-        if (!this.terminalPromise) {
-            // Reset the cached promise if the poll loop rejects (abort / deadline /
-            // attempt cap) so a later results() call can retry rather than being
-            // permanently poisoned by a transient cancellation.
-            this.terminalPromise = this.runUntilTerminal(this.resolveBudget(options)).catch((error) => {
-                this.terminalPromise = undefined;
-                throw error;
-            });
-        }
-        return this.terminalPromise;
-    }
-    /**
-     * Layer the caller's bounds over the handle's default budget, then guarantee
-     * a bound exists. NFR-001: `results()` is never an unbounded retry loop, so a
-     * caller that names neither a deadline nor an attempt cap still inherits
-     * {@link DEFAULT_POLL_DEADLINE_MS}.
-     */
-    resolveBudget(options) {
-        const merged = { ...this.pollBudget, ...options };
-        if (merged.deadlineMs !== undefined || merged.maxAttempts !== undefined)
-            return merged;
-        return { ...merged, deadlineMs: DEFAULT_POLL_DEADLINE_MS };
+        return this.lifecycle.results(options);
     }
     async cancel() {
-        if (this.terminalSnapshot) {
-            return this.currentStatus;
-        }
+        if (this.lifecycle.terminal)
+            return this.lifecycle.status;
         this.assertDismissDeclared();
+        return this.lifecycle.cancel(() => this.cancelSnapshot());
+    }
+    async cancelSnapshot() {
         try {
             // DELETE targets the job resource itself, so it follows the same
             // advertised route the status polls use rather than re-templating it.
             const cancelled = await this.client.cancelOgcProcessJob(this.jobRequest(this.statusPath));
-            const snapshot = await this.handleOgcStatus(cancelled);
-            return snapshot.status;
+            return this.translateOgcStatus(cancelled);
         }
         catch (error) {
             const statusCode = error?.statusCode;
@@ -540,7 +577,7 @@ export class HonuaOgcProcessJobRun {
             // "completed job" claim cannot be confirmed and the original 409
             // is the most honest signal.
             if (statusCode === 404) {
-                return this.currentStatus;
+                return { status: this.lifecycle.status, progress: this.lifecycle.progress };
             }
             if (statusCode === 409 && isCompletedJobConflict(error)) {
                 let fresh;
@@ -553,67 +590,24 @@ export class HonuaOgcProcessJobRun {
                     // 409 instead of letting the poll-side error swallow it.
                     throw error;
                 }
-                const snapshot = await this.handleOgcStatus(fresh);
+                const snapshot = await this.translateOgcStatus(fresh);
                 if (!isJobTerminal(snapshot.status)) {
                     throw error;
                 }
-                return snapshot.status;
+                return snapshot;
             }
             throw error;
         }
     }
-    async runUntilTerminal(options = {}) {
-        const { signal } = options;
-        const baseIntervalMs = options.pollIntervalMs ?? this.pollIntervalMs;
-        const maxIntervalMs = options.maxPollIntervalMs ?? Math.max(baseIntervalMs, 30_000);
-        const startedAt = Date.now();
-        let attempts = 0;
-        while (!this.terminalSnapshot) {
-            if (signal?.aborted) {
-                throw new HonuaJobPollTimeoutError(`Job ${this.id} poll aborted`, "aborted", this.id, this.currentStatus);
-            }
-            if (options.maxAttempts !== undefined && attempts >= options.maxAttempts) {
-                throw new HonuaJobPollTimeoutError(`Job ${this.id} did not reach a terminal state within ${options.maxAttempts} poll attempt(s)`, "max-attempts", this.id, this.currentStatus);
-            }
-            let ogcStatus;
-            try {
-                ogcStatus = await this.pollFn(this.id, signal);
-            }
-            catch (error) {
-                if (signal?.aborted) {
-                    throw new HonuaJobPollTimeoutError(`Job ${this.id} poll aborted`, "aborted", this.id, this.currentStatus);
-                }
-                throw error;
-            }
-            attempts += 1;
-            await this.handleOgcStatus(ogcStatus);
-            if (this.terminalSnapshot)
-                break;
-            if (options.deadlineMs !== undefined && Date.now() - startedAt >= options.deadlineMs) {
-                throw new HonuaJobPollTimeoutError(`Job ${this.id} did not reach a terminal state within ${options.deadlineMs}ms`, "deadline", this.id, this.currentStatus);
-            }
-            // Capped exponential backoff instead of a fixed interval.
-            const intervalMs = Math.min(maxIntervalMs, baseIntervalMs * 2 ** (attempts - 1));
-            if (intervalMs > 0) {
-                await delay(intervalMs, signal);
-            }
-        }
-        if (this.terminalSnapshot.status === "successful" && this.terminalSnapshot.result) {
-            return this.terminalSnapshot.result;
-        }
-        throw makeJobFailedError(this.terminalSnapshot);
-    }
     /**
      * Translate an OGC `statusInfo` payload onto the canonical snapshot
      * surface, fire watchers, and (for `successful` terminals) fetch the
      * result document inline so the snapshot's `result.outputs` is
      * populated by the time `runUntilTerminal` / `poll` resolves.
      */
-    async handleOgcStatus(ogcStatus) {
+    async translateOgcStatus(ogcStatus) {
         const status = ogcStatus.status ?? "accepted";
         const progress = progressFromOgcStatus(ogcStatus);
-        this.currentStatus = status;
-        this.currentProgress = progress;
         // Routes the server publishes on this document win over the Core template.
         this.absorbLinks(ogcStatus.links);
         if (status === "successful") {
@@ -634,8 +628,6 @@ export class HonuaOgcProcessJobRun {
                     progress,
                     result: { outputs: results },
                 };
-                this.terminalSnapshot = snapshot;
-                this.notify(snapshot);
                 return snapshot;
             }
             catch (error) {
@@ -653,9 +645,6 @@ export class HonuaOgcProcessJobRun {
                         message: error instanceof Error ? error.message : String(error),
                     },
                 };
-                this.currentStatus = "failed";
-                this.terminalSnapshot = failure;
-                this.notify(failure);
                 return failure;
             }
         }
@@ -666,12 +655,9 @@ export class HonuaOgcProcessJobRun {
                 progress,
                 ...(error ? { error } : {}),
             };
-            this.terminalSnapshot = snapshot;
-            this.notify(snapshot);
             return snapshot;
         }
         const snapshot = { status, progress };
-        this.notify(snapshot);
         return snapshot;
     }
     /**
@@ -690,6 +676,10 @@ export class HonuaOgcProcessJobRun {
      * in hand and neither the Dismiss conformance class nor the process's
      * `jobControlOptions` includes `dismiss`, refuse before issuing a DELETE the
      * server never advertised.
+     *
+     * Under `"strict"` the absence of any declaration refuses too: a handle that
+     * resolves declarations for itself has no honest reason to DELETE a job on a
+     * server that never said it could be dismissed.
      */
     assertDismissDeclared() {
         // Under `"strict"` the DELETE route must have been advertised, exactly as
@@ -703,25 +693,15 @@ export class HonuaOgcProcessJobRun {
         if (declares(this.jobControlOptions, JOB_CONTROL.dismiss))
             return;
         const conformsTo = this.conformance?.conformsTo;
-        if (!conformsTo)
+        if (!conformsTo && this.capabilityPolicy !== "strict")
             return;
-        if (hasOgcConformanceClass(this.conformance, PROCESSES_CONFORMANCE_MATCH.dismiss))
+        if (declaresConformanceClass(this.conformance, PROCESSES_CONFORMANCE_MATCH.dismiss))
             return;
         throw capabilityRefusal("processes.dismiss", this.type, {
             missingClass: PROCESSES_CONFORMANCE.dismiss,
             construct: JOB_CONTROL.dismiss,
         });
     }
-    notify(snapshot) {
-        for (const listener of this.listeners) {
-            try {
-                listener(snapshot);
-            }
-            catch {
-                // Listener exceptions must not break the runner; log silently.
-            }
-        }
-    }
 }
 /**
  * `IJobRun` for a synchronous execution (Core §7.11: `200` with the results
@@ -760,18 +740,7 @@ export class HonuaOgcProcessSyncRun {
     }
 }
 /** Error thrown when `IJobRun.results()` resolves a non-success terminal. */
-export class HonuaJobFailedError extends HonuaSdkError {
-    status;
-    errorCode;
-    details;
-    constructor(message, status, errorCode, details) {
-        super("core.job-failed", message, { context: { status, errorCode } });
-        this.name = "HonuaJobFailedError";
-        this.status = status;
-        this.errorCode = errorCode;
-        this.details = details;
-    }
-}
+export { HonuaJobFailedError } from "./job-run-errors.js";
 /**
  * Honua-server emits problem-details JSON for DELETE /jobs/{id} 409s. The
  * `title` distinguishes the benign terminal race ("Cannot dismiss
@@ -832,28 +801,6 @@ function clampPercent(value) {
         return 100;
     return value;
 }
-function makeJobFailedError(snapshot) {
-    const error = snapshot.error;
-    const message = error?.message ?? `Job ended in non-success terminal state: ${snapshot.status}`;
-    return new HonuaJobFailedError(message, snapshot.status, error?.code, error?.details);
-}
-function delay(ms, signal) {
-    return new Promise((resolve) => {
-        if (signal?.aborted) {
-            resolve();
-            return;
-        }
-        const onAbort = () => {
-            clearTimeout(timer);
-            resolve();
-        };
-        const timer = setTimeout(() => {
-            signal?.removeEventListener("abort", onAbort);
-            resolve();
-        }, ms);
-        signal?.addEventListener("abort", onAbort, { once: true });
-    });
-}
 export function createHonuaOgcProcesses(client) {
     return new HonuaOgcProcesses({ client });
 }
@@ -891,7 +838,7 @@ export async function getOgcProcess(transport, request) {
  * against the async-only Honua facade, and reports which shape came back.
  */
 export async function executeOgcProcess(transport, request) {
-    const headers = mergeHeaders({ "Content-Type": "application/json", Accept: "application/json" }, request.headers, preferHeaderForExecute(request));
+    const headers = executionHeaders(request);
     const path = `${processesBase(request)}/processes/${encodeURIComponent(request.processId)}/execution`;
     // `document` is the only response mode the SDK decodes: its body is the
     // output-id-keyed map that `JobResult.outputs` is defined over. (honua-server
@@ -1008,16 +955,19 @@ export async function cancelOgcProcessJob(transport, request) {
     return transport.requestJson("DELETE", withParams(route, params), undefined, request.signal);
 }
 /**
- * Build the `Prefer` header for an OGC API Processes execution request.
- * `mode: "async"` sends an explicit `Prefer: respond-async` (RFC 7240) so a
- * server that supports both shapes returns a job and OGC conformance checkers
- * see the header. `"sync"` and `"auto"` omit it: Core defines no header that
- * forces synchronous execution, so `"sync"` is expressed by *not* preferring
- * async plus the `sync-execute` capability assertion made before the post.
+ * Build the execution preference header defined by OGC API Processes 1.0.
+ * Requirement 25 selects synchronous execution by omitting `Prefer`; only an
+ * explicit asynchronous request sends the standard `respond-async` token.
+ * Clients remain prepared for either response shape.
  */
-function preferHeaderForExecute(request) {
+function executionHeaders(request) {
+    const headers = new Headers(mergeHeaders({ "Content-Type": "application/json", Accept: "application/json" }, request.headers));
+    // `mode` is the sole authority for this protocol semantic. A shared caller
+    // header bag must not silently turn `auto` / `sync` into an async request or
+    // smuggle a different preference into the explicit async mode.
+    headers.delete("Prefer");
     if (request.mode === "async") {
-        return { Prefer: "respond-async" };
+        headers.set("Prefer", "respond-async");
     }
-    return undefined;
+    return headers;
 }

package/core/process-runner.js

@@ -1,4 +1,4 @@
-import { HonuaJobPollTimeoutError } from "../contract/jobs.js";
+import { JobRunLifecycle } from "./job-run-lifecycle.js";
 export class HonuaProcessRunner {
     adapter;
     constructor(adapter) {
@@ -89,115 +89,51 @@ class GeospatialGrpcProcessJobRun {
     id;
     type = "geospatial-grpc";
     client;
-    currentStatus;
-    currentProgress;
-    terminalSnapshot;
-    terminalPromise;
-    listeners = new Set();
+    lifecycle;
     constructor(options) {
         this.client = options.client;
         this.id = readJobId(options.accepted);
-        this.currentStatus = geospatialGrpcJobStateToStatus(options.accepted.state);
+        this.lifecycle = new JobRunLifecycle({
+            id: this.id,
+            initialStatus: geospatialGrpcJobStateToStatus(options.accepted.state),
+            pollIntervalMs: 1_000,
+            poll: async (signal) => this.translateJob(await this.client.getJob({ jobId: this.id, signal })),
+        });
     }
     get status() {
-        return this.currentStatus;
+        return this.lifecycle.status;
     }
     get progress() {
-        return this.currentProgress;
+        return this.lifecycle.progress;
     }
     async poll() {
-        if (this.terminalSnapshot)
-            return this.terminalSnapshot;
-        const response = await this.client.getJob({ jobId: this.id });
-        return this.handleJob(response);
+        return this.lifecycle.poll();
     }
     watch(listener) {
-        this.listeners.add(listener);
-        return () => this.listeners.delete(listener);
+        return this.lifecycle.watch(listener);
     }
     async results(options = {}) {
-        if (!this.terminalPromise) {
-            // Reset on failure so an aborted / timed-out poll does not permanently
-            // poison subsequent results() calls.
-            this.terminalPromise = this.runUntilTerminal(options).catch((error) => {
-                this.terminalPromise = undefined;
-                throw error;
-            });
-        }
-        return this.terminalPromise;
+        return this.lifecycle.results(options);
     }
     async cancel() {
-        if (this.terminalSnapshot)
-            return this.currentStatus;
-        const response = await this.client.cancelJob({ jobId: this.id });
-        const snapshot = await this.handleJob(response);
-        return snapshot.status;
-    }
-    async runUntilTerminal(options = {}) {
-        const { signal } = options;
-        const baseIntervalMs = options.pollIntervalMs ?? 1_000;
-        const maxIntervalMs = options.maxPollIntervalMs ?? Math.max(baseIntervalMs, 30_000);
-        const startedAt = Date.now();
-        let attempts = 0;
-        while (!this.terminalSnapshot) {
-            if (signal?.aborted) {
-                throw new HonuaJobPollTimeoutError(`Job ${this.id} poll aborted`, "aborted", this.id, this.currentStatus);
-            }
-            if (options.maxAttempts !== undefined && attempts >= options.maxAttempts) {
-                throw new HonuaJobPollTimeoutError(`Job ${this.id} did not reach a terminal state within ${options.maxAttempts} poll attempt(s)`, "max-attempts", this.id, this.currentStatus);
-            }
-            let response;
-            try {
-                response = await this.client.getJob({ jobId: this.id, signal });
-            }
-            catch (error) {
-                if (signal?.aborted) {
-                    throw new HonuaJobPollTimeoutError(`Job ${this.id} poll aborted`, "aborted", this.id, this.currentStatus);
-                }
-                throw error;
-            }
-            attempts += 1;
-            await this.handleJob(response);
-            if (this.terminalSnapshot)
-                break;
-            if (options.deadlineMs !== undefined && Date.now() - startedAt >= options.deadlineMs) {
-                throw new HonuaJobPollTimeoutError(`Job ${this.id} did not reach a terminal state within ${options.deadlineMs}ms`, "deadline", this.id, this.currentStatus);
-            }
-            // Capped exponential backoff instead of a fixed 1s interval.
-            const intervalMs = Math.min(maxIntervalMs, baseIntervalMs * 2 ** (attempts - 1));
-            if (intervalMs > 0) {
-                await wait(intervalMs, signal);
-            }
-        }
-        if (this.terminalSnapshot.status === "successful" && this.terminalSnapshot.result) {
-            return this.terminalSnapshot.result;
-        }
-        throw new Error(this.terminalSnapshot.error?.message ?? `geospatial-grpc job ended in ${this.terminalSnapshot.status}`);
+        return this.lifecycle.cancel(async () => this.translateJob(await this.client.cancelJob({ jobId: this.id })));
     }
-    async handleJob(response) {
+    async translateJob(response) {
         const jobProgress = "progress" in response ? response.progress : undefined;
         const status = geospatialGrpcJobStateToStatus(response.state ?? jobProgress?.state);
         const progress = geospatialGrpcProgress(jobProgress);
-        this.currentStatus = status;
-        this.currentProgress = progress;
         if (status === "successful") {
             const result = await this.client.getJobResult({ jobId: this.id });
             const snapshot = geospatialGrpcResultSnapshot(result, progress);
-            this.terminalSnapshot = snapshot;
-            this.currentStatus = snapshot.status;
-            this.notify(snapshot);
             return snapshot;
         }
         if (status === "failed" || status === "dismissed") {
             const result = await this.safeGetTerminalResult();
             const error = result ? geospatialGrpcError(result) : undefined;
             const snapshot = { status, progress, ...(error ? { error } : {}) };
-            this.terminalSnapshot = snapshot;
-            this.notify(snapshot);
             return snapshot;
         }
         const snapshot = { status, progress };
-        this.notify(snapshot);
         return snapshot;
     }
     async safeGetTerminalResult() {
@@ -208,10 +144,6 @@ class GeospatialGrpcProcessJobRun {
             return undefined;
         }
     }
-    notify(snapshot) {
-        for (const listener of this.listeners)
-            listener(snapshot);
-    }
 }
 function requirePlan(request) {
     if (request.plan === undefined)
@@ -297,20 +229,3 @@ function timestampToIso(value) {
         return new Date(numeric).toISOString();
     return String(value);
 }
-function wait(ms, signal) {
-    return new Promise((resolve) => {
-        if (signal?.aborted) {
-            resolve();
-            return;
-        }
-        const onAbort = () => {
-            clearTimeout(timer);
-            resolve();
-        };
-        const timer = setTimeout(() => {
-            signal?.removeEventListener("abort", onAbort);
-            resolve();
-        }, ms);
-        signal?.addEventListener("abort", onAbort, { once: true });
-    });
-}