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

package/core/ogc-processes.js

@@ -1,17 +1,92 @@
 /**
  * OGC API Processes surface. Process discovery, execution, and async
- * job tracking. Per the ticket constraint, async executions return an
+ * job tracking against any conformant Part 1 (Core) server — a raw
+ * third-party deployment discovered by `discoverOgcProcesses()` just as much
+ * as the Honua facade. Per the ticket constraint, executions return an
  * `IJobRun` (the canonical async-operation surface) rather than an
- * OGC-specific job type.
+ * OGC-specific job type; a synchronous execution returns an already-terminal
+ * `IJobRun` so callers read results through one surface either way.
+ *
+ * Three properties keep the standalone lane honest:
+ *
+ * 1. **Nothing is assumed about the layout.** Routes template off the
+ *    discovered service root, and the job lifecycle prefers the server's own
+ *    `Location` header and `links[]` over the Core path template.
+ * 2. **Capability gaps fail closed.** When the server's conformance
+ *    declaration (or the process's `jobControlOptions`) is known and does not
+ *    declare what the caller asked for, the call throws
+ *    `HonuaCapabilityNotSupportedError` naming the missing construct rather
+ *    than posting and hoping.
+ * 3. **Polling is bounded.** `results()` always runs under a budget — the
+ *    caller's, the handle's, or a default deadline — and honors an
+ *    `AbortSignal`.
  *
  * @module
  */
 import { HonuaJobPollTimeoutError, isJobTerminal } from "../contract/jobs.js";
 import { HonuaSdkError } from "./error-envelope.js";
+import { HonuaCapabilityNotSupportedError } from "./errors.js";
+import { hasOgcConformanceClass } from "./ogc-conformance.js";
 import { createOgcMetadataParams, mergeHeaders } from "./wire-shared.js";
 const DEFAULT_POLL_INTERVAL_MS = 1_000;
+/**
+ * Wall-clock ceiling applied to `results()` when neither the caller nor the
+ * handle set `deadlineMs` / `maxAttempts`. NFR-001: a status endpoint that
+ * 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";
+/**
+ * OGC API — Processes Part 1 (1.0) conformance classes the SDK gates on, and
+ * the Core link relations the job lifecycle follows. These stay module-private
+ * per the `ogc-conformance` rule that conformance URIs are never top-level SDK
+ * types; they surface only as diagnostic strings inside capability errors, so a
+ * refusal can name the exact construct the server did not declare.
+ */
+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. */
+const PROCESSES_CONFORMANCE_MATCH = {
+    core: "processes-1/1.0/conf/core",
+    dismiss: "processes-1/1.0/conf/dismiss",
+};
+const PROCESSES_LINK_REL = {
+    results: "http://www.opengis.net/def/rel/ogc/1.0/results",
+    status: "self",
+};
+/** Job-control options a process declares in its description (Core §7.9). */
+const JOB_CONTROL = {
+    sync: "sync-execute",
+    async: "async-execute",
+    dismiss: "dismiss",
+};
+/**
+ * Fail-closed refusal naming the construct the server did not declare. The
+ * conformance-class URI / link relation rides in the error context so telemetry
+ * keeps it after redaction.
+ *
+ * The context key for a class URI is `missingClass`, not `conformanceClass`:
+ * the error-envelope redactor drops any key matching `form` (for form bodies),
+ * which "con**form**anceClass" hits — the value would ship as `[REDACTED]` and
+ * the refusal would name nothing.
+ */
+function capabilityRefusal(capability, sourceId, context) {
+    return new HonuaCapabilityNotSupportedError(capability, "ogc-processes", sourceId, { context });
+}
+/** `true` when the declaration list contains `option` (case-insensitive). */
+function declares(options, option) {
+    if (!options)
+        return false;
+    for (const entry of options) {
+        if (typeof entry === "string" && entry.toLowerCase() === option)
+            return true;
+    }
+    return false;
+}
 /**
  * Resolve the OGC API Processes path prefix: the caller-supplied raw `basePath`
  * (a `discoverOgcProcesses()`-discovered third-party service root) or the Honua
@@ -29,56 +104,293 @@ function processesBase(request) {
         end--;
     return base.slice(0, end);
 }
-/** Cache-key discriminator so a discovered root never collides with the facade. */
+/**
+ * Cache-key discriminator so a discovered root never collides with the facade.
+ *
+ * The base path is percent-encoded because cache keys join their components
+ * with `:` and a service root may legally contain one. Without encoding,
+ * `{ basePath: "/a", processId: "b:c" }` and `{ basePath: "/a:b", processId: "c" }`
+ * would produce the same key for two different request URLs, so a cached
+ * `describe()` could answer with the wrong process's metadata.
+ */
 function processesBaseKey(request) {
     const base = processesBase(request);
-    return base === PROCESSES_FACADE_BASE ? "" : `${base}:`;
+    return base === PROCESSES_FACADE_BASE ? "" : `${encodeURIComponent(base)}:`;
+}
+function isAbsoluteHttpUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+/**
+ * Absolute URL of a request the SDK issues against `baseUrl`. Link hrefs in the
+ * response are relative to the document that carried them, so this is the base
+ * a `links[]` entry resolves against.
+ */
+function requestUrlFor(baseUrl, path) {
+    if (!isAbsoluteHttpUrl(baseUrl))
+        return undefined;
+    try {
+        return new URL(`${baseUrl}${path}`).toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Reduce a server-advertised href to a same-origin request path.
+ *
+ * The SDK attaches credentials by header, so a link that leaves the configured
+ * origin is dropped rather than followed — the caller falls back to the Core
+ * route template (or, under `"strict"`, gets a fail-closed refusal). Relative
+ * hrefs resolve against the document that carried them.
+ */
+function advertisedRoutePath(href, documentUrl, baseUrl) {
+    if (typeof href !== "string" || href.length === 0)
+        return undefined;
+    if (!isAbsoluteHttpUrl(baseUrl))
+        return undefined;
+    let resolved;
+    try {
+        resolved = new URL(href, documentUrl ?? `${baseUrl}/`);
+    }
+    catch {
+        return undefined;
+    }
+    let origin;
+    try {
+        origin = new URL(baseUrl).origin;
+    }
+    catch {
+        return undefined;
+    }
+    if (resolved.origin !== origin)
+        return undefined;
+    return `${resolved.pathname}${resolved.search}`;
+}
+/** Core-mandated job route (§7.12) under a service root. */
+function templatedJobPath(basePath, jobId) {
+    return `${processesBase({ ...(basePath !== undefined ? { basePath } : {}) })}/jobs/${encodeURIComponent(jobId)}`;
+}
+/**
+ * Append metadata params to a route that may already carry a query string —
+ * an advertised job link often does. The server's own query is preserved
+ * verbatim (never re-encoded) and a param it already declares is never
+ * duplicated, so following a link cannot corrupt the URL the server published.
+ */
+function withParams(path, params) {
+    const queryIndex = path.indexOf("?");
+    if (queryIndex < 0) {
+        const query = params.toString();
+        return query.length === 0 ? path : `${path}?${query}`;
+    }
+    const existing = new URLSearchParams(path.slice(queryIndex + 1));
+    const additions = new URLSearchParams();
+    for (const [key, value] of params) {
+        if (!existing.has(key))
+            additions.append(key, value);
+    }
+    const query = additions.toString();
+    return query.length === 0 ? path : `${path}&${query}`;
+}
+/**
+ * First same-origin path advertised under one of `rels`, if any. A relation
+ * matches on the full URI or on its last path segment, the same tolerance
+ * `findOgcLink` applies — servers publish both
+ * `http://www.opengis.net/def/rel/ogc/1.0/results` and a bare `results`.
+ */
+function linkPath(links, documentUrl, baseUrl, ...rels) {
+    if (!links)
+        return undefined;
+    const wanted = new Set();
+    for (const rel of rels) {
+        const lower = rel.toLowerCase();
+        wanted.add(lower);
+        wanted.add(lower.slice(lower.lastIndexOf("/") + 1));
+    }
+    for (const link of links) {
+        const rel = (link.rel ?? "").toLowerCase();
+        const tail = rel.slice(rel.lastIndexOf("/") + 1);
+        if (!wanted.has(rel) && !(tail && wanted.has(tail)))
+            continue;
+        const path = advertisedRoutePath(link.href, documentUrl, baseUrl);
+        if (path)
+            return path;
+    }
+    return undefined;
 }
 /** Top-level OGC API Processes handle. */
 export class HonuaOgcProcesses {
     client;
+    basePath;
+    capabilityPolicy;
+    pollBudget;
+    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.
+     */
+    jobControlByProcess = new Map();
     constructor(options) {
         this.client = options.client;
+        this.basePath = options.basePath;
+        this.capabilityPolicy = options.capabilityPolicy ?? "advertised";
+        this.pollBudget = options.pollBudget;
+        this.declaredConformance = options.conformance;
+    }
+    withBase(request) {
+        return this.basePath !== undefined ? { ...request, basePath: this.basePath } : request;
     }
     async landing(request = {}) {
-        return this.client.getOgcProcessesLanding(request);
+        return this.client.getOgcProcessesLanding(this.withBase(request));
     }
     async conformance(request = {}) {
-        return this.client.getOgcProcessesConformance(request);
+        const response = await this.client.getOgcProcessesConformance(this.withBase(request));
+        if (Array.isArray(response?.conformsTo))
+            this.declaredConformance = response;
+        return response;
     }
     async list(request = {}) {
-        return this.client.listOgcProcesses(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]);
+            }
+        }
+        return response;
     }
     async describe(processId, request = {}) {
-        return this.client.getOgcProcess({ ...request, processId });
+        const description = await this.client.getOgcProcess(this.withBase({ ...request, processId }));
+        if (description?.jobControlOptions) {
+            this.jobControlByProcess.set(processId, [...description.jobControlOptions]);
+        }
+        return description;
     }
     /**
-     * Submit a process for execution. Always returns an `IJobRun`: honua-server
-     * is async-only (advertises `jobControlOptions: ['async-execute', 'dismiss']`),
-     * so the runner polls for the terminal snapshot regardless of whether
-     * `mode` is `"async"` or `"auto"`.
+     * Submit a process for execution and return an `IJobRun` — always, so the
+     * caller reads results through one surface whichever Core response shape the
+     * server chose:
+     *
+     * - asynchronous (`Prefer: respond-async`, or the server's own default) →
+     *   a pollable run bound to the advertised job routes.
+     * - synchronous (`200` with the results document) → an already-terminal run
+     *   whose `results()` resolves immediately with zero further requests.
+     *
+     * Before anything is posted, `mode` is gated against what the server has
+     * declared: the Core conformance class when a conformance declaration is in
+     * hand, and the process's `jobControlOptions` when the description is (from
+     * `request.jobControlOptions`, an earlier `describe()`/`list()` on this
+     * handle, or — under `capabilityPolicy: "strict"` — a cached `describe()`
+     * performed here). An undeclared mode fails closed with
+     * `HonuaCapabilityNotSupportedError`.
      */
     async execute(request) {
-        const accepted = await this.client.executeOgcProcess(request);
+        const executeRequest = this.withBase(request);
+        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);
+        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.
+            return new HonuaOgcProcessSyncRun(processId, (accepted.results ?? {}));
+        }
         return new HonuaOgcProcessJobRun({
             client: this.client,
             jobId: accepted.jobID,
-            processId: accepted.processID ?? request.processId,
+            processId,
             initialStatus: accepted.statusInfo ?? {
                 jobID: accepted.jobID,
-                processID: accepted.processID ?? request.processId,
+                processID: processId,
                 status: accepted.status,
             },
+            // The job routes live under the same root the execution was posted to;
+            // a job created against a discovered root must never poll the facade.
+            ...(executeRequest.basePath !== undefined ? { basePath: executeRequest.basePath } : {}),
+            ...(accepted.statusPath !== undefined ? { statusPath: accepted.statusPath } : {}),
+            ...(this.pollBudget !== undefined ? { pollBudget: this.pollBudget } : {}),
+            ...(conformance !== undefined ? { conformance } : {}),
+            ...(jobControlOptions !== undefined ? { jobControlOptions } : {}),
+            capabilityPolicy: this.capabilityPolicy,
         });
     }
     /** 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;
         return new HonuaOgcProcessJobRun({
             client: this.client,
             jobId,
             processId: options.processId,
+            ...(basePath !== undefined ? { basePath } : {}),
+            ...(options.statusPath !== undefined ? { statusPath: options.statusPath } : {}),
+            ...(options.resultsPath !== undefined ? { resultsPath: options.resultsPath } : {}),
+            ...(this.pollBudget !== undefined ? { pollBudget: this.pollBudget } : {}),
+            ...(this.declaredConformance !== undefined ? { conformance: this.declaredConformance } : {}),
+            ...(jobControlOptions !== undefined ? { jobControlOptions } : {}),
+            capabilityPolicy: this.capabilityPolicy,
         });
     }
+    /**
+     * Resolve the conformance declaration. Under `"advertised"` only what the
+     * caller already supplied (or a `conformance()` call made through this
+     * handle) counts; under `"strict"` the declaration is fetched once through
+     * the metadata cache so a refusal can be grounded in the server's own words.
+     */
+    async resolveConformance(signal) {
+        if (this.declaredConformance)
+            return this.declaredConformance;
+        if (this.capabilityPolicy !== "strict")
+            return undefined;
+        if (!this.conformancePromise) {
+            const request = signal ? { signal } : {};
+            this.conformancePromise = this.client
+                .getOgcProcessesConformance(this.withBase(request))
+                .then((response) => {
+                this.declaredConformance = response;
+                return response;
+            })
+                .catch((error) => {
+                this.conformancePromise = undefined;
+                throw error;
+            });
+        }
+        return this.conformancePromise;
+    }
+    /**
+     * Fail closed when the server has not declared what the caller asked for.
+     * Returns the conformance declaration (when one is in hand) so the created
+     * job run can reuse it to gate `cancel()`.
+     */
+    async assertExecutionDeclared(request) {
+        const conformance = await this.resolveConformance(request.signal);
+        if (conformance?.conformsTo && !hasOgcConformanceClass(conformance, PROCESSES_CONFORMANCE_MATCH.core)) {
+            throw capabilityRefusal("processes.execute", request.processId, {
+                missingClass: PROCESSES_CONFORMANCE.core,
+                construct: "execute",
+            });
+        }
+        const mode = request.mode ?? "auto";
+        // `auto` asserts nothing about sync vs async: the server picks, and both
+        // 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);
+        if (!jobControlOptions && this.capabilityPolicy === "strict") {
+            const description = await this.describe(request.processId, request.signal ? { signal: request.signal } : {});
+            jobControlOptions = description.jobControlOptions;
+        }
+        if (!jobControlOptions)
+            return conformance;
+        const required = mode === "sync" ? JOB_CONTROL.sync : JOB_CONTROL.async;
+        if (!declares(jobControlOptions, required)) {
+            throw capabilityRefusal(`processes.${required}`, request.processId, {
+                construct: required,
+                declaredJobControlOptions: jobControlOptions.join(","),
+            });
+        }
+        return conformance;
+    }
 }
 /**
  * `IJobRun` implementation backed by OGC API Processes 1.0 status / result
@@ -91,8 +403,16 @@ export class HonuaOgcProcessJobRun {
     id;
     type;
     client;
+    basePath;
     pollIntervalMs;
     pollFn;
+    pollBudget;
+    conformance;
+    jobControlOptions;
+    capabilityPolicy;
+    /** Server-advertised routes, refreshed from every `links[]` the job reports. */
+    statusPath;
+    resultsPath;
     currentStatus;
     currentProgress;
     terminalSnapshot;
@@ -102,12 +422,53 @@ export class HonuaOgcProcessJobRun {
         this.client = options.client;
         this.id = options.jobId;
         this.type = options.processId ?? options.initialStatus?.processID ?? "unknown";
+        this.basePath = options.basePath;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-        this.pollFn = options.pollFn ?? ((jobId, signal) => options.client.getOgcProcessJob({ jobId, signal }));
+        this.pollBudget = options.pollBudget;
+        this.conformance = options.conformance;
+        this.jobControlOptions = options.jobControlOptions;
+        this.capabilityPolicy = options.capabilityPolicy ?? "advertised";
+        this.statusPath = options.statusPath;
+        this.resultsPath = options.resultsPath;
+        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);
     }
+    async fetchStatus(jobId, signal) {
+        if (this.capabilityPolicy === "strict" && this.statusPath === undefined) {
+            throw capabilityRefusal("processes.jobStatusLink", this.type, {
+                construct: "job status route",
+                linkRelation: PROCESSES_LINK_REL.status,
+            });
+        }
+        return this.client.getOgcProcessJob({
+            jobId,
+            ...(signal ? { signal } : {}),
+            ...(this.basePath !== undefined ? { basePath: this.basePath } : {}),
+            ...(this.statusPath !== undefined ? { routePath: this.statusPath } : {}),
+        });
+    }
+    /**
+     * Adopt the routes the server advertises on a job document. Every poll can
+     * refresh them, so a server that only publishes its results link once the
+     * job succeeds is still followed rather than path-guessed.
+     */
+    absorbLinks(links) {
+        if (!links || links.length === 0)
+            return;
+        const baseUrl = this.client.serverBaseUrl;
+        const documentUrl = requestUrlFor(baseUrl, this.statusPath ?? templatedJobPath(this.basePath, this.id));
+        const results = linkPath(links, documentUrl, baseUrl, PROCESSES_LINK_REL.results);
+        if (results)
+            this.resultsPath = results;
+        if (this.statusPath === undefined) {
+            const status = linkPath(links, documentUrl, baseUrl, PROCESSES_LINK_REL.status, "status", "monitor");
+            if (status)
+                this.statusPath = status;
+        }
+    }
     get status() {
         return this.currentStatus;
     }
@@ -130,19 +491,34 @@ export class HonuaOgcProcessJobRun {
             // 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(options).catch((error) => {
+            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 };
+    }
     async cancel() {
         if (this.terminalSnapshot) {
             return this.currentStatus;
         }
+        this.assertDismissDeclared();
         try {
-            const cancelled = await this.client.cancelOgcProcessJob({ jobId: this.id });
+            // 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;
         }
@@ -238,13 +614,21 @@ export class HonuaOgcProcessJobRun {
         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") {
             try {
+                if (this.capabilityPolicy === "strict" && this.resultsPath === undefined) {
+                    throw capabilityRefusal("processes.jobResultsLink", this.type, {
+                        construct: "job results route",
+                        linkRelation: PROCESSES_LINK_REL.results,
+                    });
+                }
                 // Per OGC API Processes §7.11.1 the document-mode result body is the
                 // outputs map itself (honua-server returns `{}` for the canonical
                 // V1 process; populated maps are keyed by output id). Wrap it into
                 // the canonical `JobResult.outputs` envelope.
-                const results = await this.client.getOgcProcessJobResults({ jobId: this.id });
+                const results = await this.client.getOgcProcessJobResults(this.jobRequest(this.resultsPath));
                 const snapshot = {
                     status: "successful",
                     progress,
@@ -255,6 +639,12 @@ export class HonuaOgcProcessJobRun {
                 return snapshot;
             }
             catch (error) {
+                // A fail-closed capability refusal is not a job failure: the job may
+                // well have succeeded, the SDK simply refuses to guess the route.
+                // Surfacing it as `failed` would launder a client-side refusal into a
+                // server-side outcome.
+                if (error instanceof HonuaCapabilityNotSupportedError)
+                    throw error;
                 const failure = {
                     status: "failed",
                     progress,
@@ -284,6 +674,44 @@ export class HonuaOgcProcessJobRun {
         this.notify(snapshot);
         return snapshot;
     }
+    /**
+     * Job-route envelope pinned to the root the job was created against,
+     * preferring a route the server advertised over the Core path template.
+     */
+    jobRequest(routePath) {
+        return {
+            jobId: this.id,
+            ...(this.basePath !== undefined ? { basePath: this.basePath } : {}),
+            ...(routePath !== undefined ? { routePath } : {}),
+        };
+    }
+    /**
+     * Dismissal is an optional Core extension. When the server's declaration is
+     * in hand and neither the Dismiss conformance class nor the process's
+     * `jobControlOptions` includes `dismiss`, refuse before issuing a DELETE the
+     * server never advertised.
+     */
+    assertDismissDeclared() {
+        // Under `"strict"` the DELETE route must have been advertised, exactly as
+        // the status route must be, so dismissal is never sent to a guessed path.
+        if (this.capabilityPolicy === "strict" && this.statusPath === undefined) {
+            throw capabilityRefusal("processes.jobStatusLink", this.type, {
+                construct: "job status route",
+                linkRelation: PROCESSES_LINK_REL.status,
+            });
+        }
+        if (declares(this.jobControlOptions, JOB_CONTROL.dismiss))
+            return;
+        const conformsTo = this.conformance?.conformsTo;
+        if (!conformsTo)
+            return;
+        if (hasOgcConformanceClass(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 {
@@ -295,6 +723,42 @@ export class HonuaOgcProcessJobRun {
         }
     }
 }
+/**
+ * `IJobRun` for a synchronous execution (Core §7.11: `200` with the results
+ * document inline). No job resource exists on the server, so the run starts
+ * terminal: `results()` resolves from memory, `poll()` replays the terminal
+ * snapshot, and `cancel()` is a no-op that reports the outcome that already
+ * happened. Callers therefore read a sync and an async execution through one
+ * surface.
+ */
+export class HonuaOgcProcessSyncRun {
+    /** Empty: OGC Processes assigns no job identifier to a synchronous execution. */
+    id = "";
+    type;
+    status = "successful";
+    progress = { percent: 100 };
+    snapshot;
+    constructor(processId, outputs) {
+        this.type = processId;
+        this.snapshot = { status: "successful", progress: this.progress, result: { outputs } };
+    }
+    async poll() {
+        return this.snapshot;
+    }
+    watch(listener) {
+        // The only transition already happened; replay it so watchers registered
+        // after a synchronous execution still observe the terminal snapshot.
+        listener(this.snapshot);
+        return () => { };
+    }
+    async results() {
+        // Non-null: the constructor always builds a `successful` snapshot with a result.
+        return this.snapshot.result;
+    }
+    async cancel() {
+        return "successful";
+    }
+}
 /** Error thrown when `IJobRun.results()` resolves a non-success terminal. */
 export class HonuaJobFailedError extends HonuaSdkError {
     status;
@@ -411,37 +875,145 @@ export async function listOgcProcesses(transport, request = {}) {
 }
 export async function getOgcProcess(transport, request) {
     const params = createOgcMetadataParams(request);
-    return transport.requestCachedMetadataJson(`ogc-processes:process:${request.processId}:${params.toString()}`, `/ogc/processes/processes/${encodeURIComponent(request.processId)}?${params.toString()}`, request);
+    const base = processesBase(request);
+    return transport.requestCachedMetadataJson(
+    // Both components are percent-encoded so neither can smuggle the `:`
+    // separator and alias a different (basePath, processId) pair.
+    `ogc-processes:process:${processesBaseKey(request)}${encodeURIComponent(request.processId)}:${params.toString()}`, `${base}/processes/${encodeURIComponent(request.processId)}?${params.toString()}`, request);
 }
+/**
+ * `POST /processes/{processId}/execution` (Core §7.11).
+ *
+ * Core defines two success shapes and a conformant server may choose either:
+ * `200` with the results document (synchronous) or `201` + `Location` with a
+ * `statusInfo` body (asynchronous). This reads the response rather than
+ * assuming one, so the same call works against a raw third-party server and
+ * 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 path = `/ogc/processes/processes/${encodeURIComponent(request.processId)}/execution`;
-    // honua-server only supports `response: "document"` and rejects "raw"
-    // with HTTP 501; the SDK pins the supported value here.
+    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
+    // additionally rejects `raw` with HTTP 501.)
     const body = JSON.stringify({
         inputs: request.inputs ?? {},
         outputs: request.outputs,
         response: "document",
     });
-    return transport.requestJson("POST", path, { headers, body }, request.signal);
+    // pipelineFetch over requestJson: Core distinguishes the synchronous and
+    // asynchronous outcomes by status code and `Location`, both of which a
+    // JSON-only helper discards.
+    const response = await transport.pipelineFetch("POST", path, { headers, body }, request.signal);
+    const payload = await readExecutionPayload(response);
+    const statusInfo = asJobStatusInfo(payload, request.processId);
+    const documentUrl = requestUrlFor(transport.baseUrl, path);
+    const location = advertisedRoutePath(response.headers.get("Location") ?? undefined, documentUrl, transport.baseUrl);
+    if (statusInfo) {
+        const statusPath = location ?? linkPath(statusInfo.links, documentUrl, transport.baseUrl, PROCESSES_LINK_REL.status, "status");
+        return {
+            jobID: statusInfo.jobID,
+            status: statusInfo.status,
+            processID: statusInfo.processID ?? request.processId,
+            ...(statusInfo.links ? { links: [...statusInfo.links] } : {}),
+            statusInfo,
+            ...(statusPath !== undefined ? { statusPath } : {}),
+            synchronous: false,
+        };
+    }
+    if (location !== undefined) {
+        // `201 Location` with no (or an unrecognized) body: the job exists and the
+        // server named its route. Derive the id from the advertised route's last
+        // segment rather than inventing one.
+        const jobId = jobIdFromRoute(location);
+        return {
+            jobID: jobId,
+            status: "accepted",
+            processID: request.processId,
+            statusPath: location,
+            synchronous: false,
+        };
+    }
+    // No job identifier and no job route: Core leaves only the synchronous shape,
+    // whose body IS the results document.
+    return {
+        jobID: "",
+        status: "successful",
+        processID: request.processId,
+        results: (payload ?? {}),
+        synchronous: true,
+    };
+}
+/**
+ * Decode an execution response body. A `204` (or empty body) yields
+ * `undefined`; a non-JSON body is refused rather than guessed at, because the
+ * SDK asked for `response: "document"` and can only project a JSON outputs map
+ * onto `JobResult.outputs`.
+ */
+async function readExecutionPayload(response) {
+    if (response.status === 204)
+        return undefined;
+    const text = await response.text();
+    if (text.trim().length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw capabilityRefusal("processes.documentResponse", undefined, {
+            construct: "document-mode execution response",
+            contentType: response.headers.get("Content-Type") ?? "unknown",
+        });
+    }
+}
+/** Recognize an async `statusInfo` body: Core requires a non-empty `jobID`. */
+function asJobStatusInfo(payload, processId) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return undefined;
+    const candidate = payload;
+    if (typeof candidate.jobID !== "string" || candidate.jobID.length === 0)
+        return undefined;
+    return {
+        ...candidate,
+        jobID: candidate.jobID,
+        processID: candidate.processID ?? processId,
+        status: candidate.status ?? "accepted",
+    };
+}
+/** Last path segment of an advertised job route, decoded. */
+function jobIdFromRoute(routePath) {
+    const withoutQuery = routePath.split("?", 1)[0] ?? routePath;
+    const trimmed = withoutQuery.endsWith("/") ? withoutQuery.slice(0, -1) : withoutQuery;
+    const segment = trimmed.slice(trimmed.lastIndexOf("/") + 1);
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
 }
 export async function getOgcProcessJob(transport, request) {
     const params = createOgcMetadataParams(request);
-    return transport.requestJson("GET", `/ogc/processes/jobs/${encodeURIComponent(request.jobId)}?${params.toString()}`, undefined, request.signal);
+    const route = request.routePath ?? `${processesBase(request)}/jobs/${encodeURIComponent(request.jobId)}`;
+    return transport.requestJson("GET", withParams(route, params), undefined, request.signal);
 }
 export async function getOgcProcessJobResults(transport, request) {
     const params = createOgcMetadataParams(request);
-    return transport.requestJson("GET", `/ogc/processes/jobs/${encodeURIComponent(request.jobId)}/results?${params.toString()}`, undefined, request.signal);
+    const route = request.routePath ?? `${processesBase(request)}/jobs/${encodeURIComponent(request.jobId)}/results`;
+    return transport.requestJson("GET", withParams(route, params), undefined, request.signal);
 }
 export async function cancelOgcProcessJob(transport, request) {
     const params = createOgcMetadataParams(request);
-    return transport.requestJson("DELETE", `/ogc/processes/jobs/${encodeURIComponent(request.jobId)}?${params.toString()}`, undefined, request.signal);
+    const route = request.routePath ?? `${processesBase(request)}/jobs/${encodeURIComponent(request.jobId)}`;
+    return transport.requestJson("DELETE", withParams(route, params), undefined, request.signal);
 }
 /**
  * Build the `Prefer` header for an OGC API Processes execution request.
- * honua-server is async-only: `mode: "async"` sends an explicit
- * `Prefer: respond-async` so OGC-conformance checkers see the header;
- * `mode: "auto"` (or unset) omits it and lets the server default apply.
+ * `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.
  */
 function preferHeaderForExecute(request) {
     if (request.mode === "async") {