From b049a4ee80442417c9e4225df44ef6a3fd1b583d Mon Sep 17 00:00:00 2001
From: Makisuo <minetoaster12@gmail.com>
Date: Tue, 1 Sep 2026 16:58:54 +0200
Subject: [PATCH 1/2] fix(domain): register the attribute-mapping forbidden
 error as anticipated

`IngestAttributeMappingForbiddenError` was added with the admin gate but never
regenerated into `ANTICIPATED_ERROR_IDENTIFIER_LIST`, so the drift test that
compares the checked-in list against reflection has been failing on main since.

Regenerated output only. Without it the error counts as a 5xx-style failure in
the SDK's span status, so an ordinary 403 would show up as an error event.
---
 packages/domain/src/generated/anticipated-error-identifiers.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/domain/src/generated/anticipated-error-identifiers.ts b/packages/domain/src/generated/anticipated-error-identifiers.ts
index 32592a5fa..add5dd953 100644
--- a/packages/domain/src/generated/anticipated-error-identifiers.ts
+++ b/packages/domain/src/generated/anticipated-error-identifiers.ts
@@ -47,6 +47,7 @@ export const ANTICIPATED_ERROR_IDENTIFIER_LIST: ReadonlyArray<string> = [
 	"@maple/http/errors/ErrorIssuePullRequestNotFoundError",
 	"@maple/http/errors/ErrorIssueTransitionError",
 	"@maple/http/errors/ErrorValidationError",
+	"@maple/http/errors/IngestAttributeMappingForbiddenError",
 	"@maple/http/errors/IngestAttributeMappingNotFoundError",
 	"@maple/http/errors/IngestAttributeMappingValidationError",
 	"@maple/http/errors/IntegrationsForbiddenError",

From a6ae916b1757e1a7d046f828c4b043794d505b32 Mon Sep 17 00:00:00 2001
From: Makisuo <minetoaster12@gmail.com>
Date: Tue, 1 Sep 2026 16:59:08 +0200
Subject: [PATCH 2/2] refactor(url): parse URLs as values instead of catching
 TypeErrors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`new URL(...)` throws a `TypeError` the type system cannot see, and every
`catch` answering it flattens "not a URL" together with whatever else the block
could fail on. Eight sites were spelling that out by hand, each with its own
copy of the recovery.

`@maple/domain/url` holds the three shapes they wanted — `parseUrl` (Option),
`parseUrlWithBase` for the relative form, and `urlPathname`, whose empty string
is what the request predicates were expressing as `catch { return false }`. The
existing local copies in `pull-request-ref` and `github-hosts` now use it too.

Two behaviour changes fall out of the sweep:

- `safeFetch` resolved a redirect's `Location` with a bare
  `new URL(location, validated)`. That header is whatever the far end sent, so a
  malformed one threw a raw `TypeError` out of the SSRF guard — neither a
  rejection callers can handle nor a response. It is a `UrlValidationError` now,
  with a regression test.
- `validateExternalUrlSync` threw `UrlValidationError`, a `Schema.TaggedError`,
  which the Effect wrapper then had to re-recognise on the way back out. The
  check is `validateExternalUrlResult` returning a `Result`, `validateExternalUrl`
  is `Effect.fromResult` over it, and its two callers read the failure instead of
  catching it. All 69 existing guard cases are kept, as Result assertions.

`safeFetch` itself stays a Promise: moving it onto `HttpClient` is a rewrite of
the redirect and credential-stripping loop, not a parsing change.
---
 apps/api/src/http/url-validator.test.ts       | 53 ++++++++---
 apps/api/src/http/url-validator.ts            | 87 +++++++++++--------
 apps/api/src/platform/WorkersAiHttpClient.ts  | 15 ++--
 .../PlanetScaleDiscoveryService.ts            |  6 +-
 .../vcs/vendor/github/GithubProvider.ts       | 10 +--
 .../vcs/vendor/github/github-hosts.ts         | 13 +--
 apps/api/src/worker.ts                        | 29 ++-----
 packages/domain/package.json                  |  1 +
 packages/domain/src/http/pull-request-ref.ts  | 19 ++--
 packages/domain/src/url.test.ts               | 51 +++++++++++
 packages/domain/src/url.ts                    | 45 ++++++++++
 .../query-engine/src/execution/backend.ts     | 12 +--
 12 files changed, 226 insertions(+), 115 deletions(-)
 create mode 100644 packages/domain/src/url.test.ts
 create mode 100644 packages/domain/src/url.ts

diff --git a/apps/api/src/http/url-validator.test.ts b/apps/api/src/http/url-validator.test.ts
index cab778997..f4353ea0b 100644
--- a/apps/api/src/http/url-validator.test.ts
+++ b/apps/api/src/http/url-validator.test.ts
@@ -1,22 +1,40 @@
 import { assert, describe, expect, it } from "@effect/vitest"
-import { Effect } from "effect"
-import { safeFetch, UrlValidationError, validateExternalUrl, validateExternalUrlSync } from "./url-validator"
+import { Effect, Result } from "effect"
+import {
+	safeFetch,
+	UrlValidationError,
+	validateExternalUrl,
+	validateExternalUrlResult,
+} from "./url-validator"
 
-describe("validateExternalUrlSync", () => {
+/** Rejected, and rejected as the tagged error rather than by throwing. */
+const rejects = (raw: string): void => {
+	const result = validateExternalUrlResult(raw)
+	assert.isTrue(Result.isFailure(result), `expected ${raw} to be rejected`)
+	if (Result.isFailure(result)) expect(result.failure).toBeInstanceOf(UrlValidationError)
+}
+
+const accepts = (raw: string): URL => {
+	const result = validateExternalUrlResult(raw)
+	assert.isTrue(Result.isSuccess(result), `expected ${raw} to be accepted`)
+	return Result.isSuccess(result) ? result.success : new URL("https://unreachable.invalid")
+}
+
+describe("validateExternalUrlResult", () => {
 	it("accepts public https URLs", () => {
-		const url = validateExternalUrlSync("https://api.example.com/probe")
+		const url = accepts("https://api.example.com/probe")
 		expect(url.hostname).toBe("api.example.com")
 	})
 
 	it("accepts public http URLs", () => {
-		const url = validateExternalUrlSync("http://prom.public.dev:9090/metrics")
+		const url = accepts("http://prom.public.dev:9090/metrics")
 		expect(url.hostname).toBe("prom.public.dev")
 	})
 
 	it.each(["javascript:alert(1)", "file:///etc/passwd", "ftp://example.com", "data:text/html,<script>"])(
 		"rejects non-http(s) scheme: %s",
 		(raw) => {
-			expect(() => validateExternalUrlSync(raw)).toThrow(UrlValidationError)
+			rejects(raw)
 		},
 	)
 
@@ -66,7 +84,7 @@ describe("validateExternalUrlSync", () => {
 		"http://239.255.255.250/",
 		"http://240.0.0.1/",
 	])("rejects private/loopback host: %s", (raw) => {
-		expect(() => validateExternalUrlSync(raw)).toThrow(UrlValidationError)
+		rejects(raw)
 	})
 
 	// The parser's host here is `internal`, not `real.example.com` — the credentials
@@ -74,7 +92,7 @@ describe("validateExternalUrlSync", () => {
 	it.each(["https://real.example.com@localhost/", "https://user:pw@api.example.com/"])(
 		"rejects embedded credentials: %s",
 		(raw) => {
-			expect(() => validateExternalUrlSync(raw)).toThrow(UrlValidationError)
+			rejects(raw)
 		},
 	)
 
@@ -97,16 +115,16 @@ describe("validateExternalUrlSync", () => {
 		"https://127.acme.io/hook",
 		"https://192.168.example.com/hook",
 	])("accepts public host: %s", (raw) => {
-		expect(() => validateExternalUrlSync(raw)).not.toThrow()
+		accepts(raw)
 	})
 
 	it("rejects empty string", () => {
-		expect(() => validateExternalUrlSync("")).toThrow(UrlValidationError)
-		expect(() => validateExternalUrlSync("   ")).toThrow(UrlValidationError)
+		rejects("")
+		rejects("   ")
 	})
 
 	it("rejects malformed input", () => {
-		expect(() => validateExternalUrlSync("not a url")).toThrow(UrlValidationError)
+		rejects("not a url")
 	})
 })
 
@@ -163,6 +181,17 @@ describe("safeFetch", () => {
 		expect(calls).toBe(1)
 	})
 
+	// The far end controls `Location`. Resolving it with a bare
+	// `new URL(location, validated)` threw a raw TypeError out of the guard, which
+	// is neither a rejection callers can handle nor a response.
+	it("rejects a redirect whose Location is not a URL", async () => {
+		const fakeFetch: typeof fetch = async () =>
+			new Response(null, { status: 302, headers: { location: "http://" } })
+		await expect(
+			safeFetch("https://api.example.com/x", { fetchFn: fakeFetch }),
+		).rejects.toBeInstanceOf(UrlValidationError)
+	})
+
 	it("follows a redirect to another public URL", async () => {
 		let calls = 0
 		const fakeFetch: typeof fetch = async (input) => {
diff --git a/apps/api/src/http/url-validator.ts b/apps/api/src/http/url-validator.ts
index 0905e4ef5..a4123080a 100644
--- a/apps/api/src/http/url-validator.ts
+++ b/apps/api/src/http/url-validator.ts
@@ -1,4 +1,5 @@
-import { Effect, Schema } from "effect"
+import { Effect, Option, Result, Schema } from "effect"
+import { parseUrl, parseUrlWithBase } from "@maple/domain/url"
 
 export class UrlValidationError extends Schema.TaggedError<UrlValidationError>()(
 	"@maple/api/lib/UrlValidationError",
@@ -137,55 +138,60 @@ const isPrivateHost = (hostname: string): boolean => {
 	return false
 }
 
-export const validateExternalUrlSync = (raw: string): URL => {
+/**
+ * The validation itself, as a value.
+ *
+ * Every rejection is a `UrlValidationError`, so the whole check reads as one
+ * `Result` rather than a throwing function wrapped in an `Effect.try` that has
+ * to re-recognise its own tagged error on the way back out. `parseUrl` is what
+ * keeps the parse total: `new URL(...)` in a `try` throws a `TypeError` the type
+ * system cannot see, and the `catch` answering it cannot tell "not a URL" from
+ * any other failure in the block.
+ */
+export const validateExternalUrlResult = (raw: string): Result.Result<URL, UrlValidationError> => {
 	const trimmed = raw.trim()
 	if (trimmed.length === 0) {
-		throw new UrlValidationError({ message: "URL is required" })
+		return Result.fail(new UrlValidationError({ message: "URL is required" }))
 	}
-	let parsed: URL
-	try {
-		parsed = new URL(trimmed)
-	} catch {
-		throw new UrlValidationError({ message: `Invalid URL: ${trimmed}`, url: trimmed })
+	const decoded = parseUrl(trimmed)
+	if (Option.isNone(decoded)) {
+		return Result.fail(new UrlValidationError({ message: `Invalid URL: ${trimmed}`, url: trimmed }))
 	}
+	const parsed = decoded.value
 	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-		throw new UrlValidationError({
-			message: `URL scheme '${parsed.protocol}' is not allowed; use http or https`,
-			url: trimmed,
-		})
+		return Result.fail(
+			new UrlValidationError({
+				message: `URL scheme '${parsed.protocol}' is not allowed; use http or https`,
+				url: trimmed,
+			}),
+		)
 	}
 	if (parsed.hostname.length === 0) {
-		throw new UrlValidationError({ message: "URL must include a hostname", url: trimmed })
+		return Result.fail(
+			new UrlValidationError({ message: "URL must include a hostname", url: trimmed }),
+		)
 	}
 	// Credentials in the URL are both a way to smuggle a second host past a
 	// reader (`https://real.example.com@internal/`, where the parser's host is
 	// `internal`) and a way to have Maple replay them at the destination.
 	if (parsed.username !== "" || parsed.password !== "") {
-		throw new UrlValidationError({
-			message: "URL must not embed credentials",
-			url: trimmed,
-		})
+		return Result.fail(
+			new UrlValidationError({ message: "URL must not embed credentials", url: trimmed }),
+		)
 	}
 	if (isPrivateHost(parsed.hostname)) {
-		throw new UrlValidationError({
-			message: `URL host '${parsed.hostname}' is not allowed (loopback, private, or metadata range)`,
-			url: trimmed,
-		})
+		return Result.fail(
+			new UrlValidationError({
+				message: `URL host '${parsed.hostname}' is not allowed (loopback, private, or metadata range)`,
+				url: trimmed,
+			}),
+		)
 	}
-	return parsed
+	return Result.succeed(parsed)
 }
 
 export const validateExternalUrl = (raw: string): Effect.Effect<URL, UrlValidationError> =>
-	Effect.try({
-		try: () => validateExternalUrlSync(raw),
-		catch: (error) =>
-			error instanceof UrlValidationError
-				? error
-				: new UrlValidationError({
-						message: error instanceof Error ? error.message : "URL validation failed",
-						url: raw,
-					}),
-	})
+	Effect.fromResult(validateExternalUrlResult(raw))
 
 const MAX_REDIRECTS = 5
 
@@ -213,7 +219,9 @@ export const safeFetch = async (initialUrl: string, init: SafeFetchOptions = {})
 	let headers = init.headers
 	let previousOrigin: string | null = null
 	for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
-		const validated = validateExternalUrlSync(currentUrl)
+		const checked = validateExternalUrlResult(currentUrl)
+		if (Result.isFailure(checked)) throw checked.failure
+		const validated = checked.success
 		// A cross-origin hop drops the credentials for good: restoring them on a
 		// bounce back to the original origin would make the strip trivially
 		// bypassable by redirecting away and back again.
@@ -225,7 +233,18 @@ export const safeFetch = async (initialUrl: string, init: SafeFetchOptions = {})
 		if (response.status < 300 || response.status >= 400) return response
 		const location = response.headers.get("location")
 		if (!location) return response
-		currentUrl = new URL(location, validated).toString()
+		// `Location` is whatever the far end sent. Resolving it with a bare
+		// `new URL(location, validated)` threw a raw `TypeError` out of the SSRF
+		// guard on a malformed header — the one failure here that was neither a
+		// `UrlValidationError` nor a response.
+		const next = parseUrlWithBase(location, validated)
+		if (Option.isNone(next)) {
+			throw new UrlValidationError({
+				message: `Redirect target is not a URL: ${location}`,
+				url: validated.toString(),
+			})
+		}
+		currentUrl = next.value.toString()
 	}
 	throw new UrlValidationError({
 		message: `Too many redirects (>${MAX_REDIRECTS})`,
diff --git a/apps/api/src/platform/WorkersAiHttpClient.ts b/apps/api/src/platform/WorkersAiHttpClient.ts
index 9affe6017..cfff3b86d 100644
--- a/apps/api/src/platform/WorkersAiHttpClient.ts
+++ b/apps/api/src/platform/WorkersAiHttpClient.ts
@@ -25,6 +25,7 @@
  */
 import { Effect, Layer, Predicate } from "effect"
 import { HttpClient, HttpClientError, HttpClientResponse, type HttpClientRequest } from "effect/unstable/http"
+import { urlPathname } from "@maple/domain/url"
 
 /** The subset of the Cloudflare `Ai` binding this shim uses. */
 export interface WorkersAiBinding {
@@ -52,15 +53,11 @@ export const isWorkersAiBinding = (value: unknown): value is WorkersAiBinding =>
  * `.../accounts/{id}/ai/v1/chat/completions` form and an AI Gateway `.../compat/chat/completions`.
  */
 const isWorkersAiChatUrl = (url: string): boolean => {
-	try {
-		const { pathname } = new URL(url)
-		return (
-			pathname.endsWith("/chat/completions") &&
-			(pathname.includes("/ai/v1/") || pathname.includes("/compat/"))
-		)
-	} catch {
-		return false
-	}
+	const pathname = urlPathname(url)
+	return (
+		pathname.endsWith("/chat/completions") &&
+		(pathname.includes("/ai/v1/") || pathname.includes("/compat/"))
+	)
 }
 
 const encodeError = (request: HttpClientRequest.HttpClientRequest, cause: unknown) =>
diff --git a/apps/api/src/services/integrations/PlanetScaleDiscoveryService.ts b/apps/api/src/services/integrations/PlanetScaleDiscoveryService.ts
index ffd249267..d5581ae69 100644
--- a/apps/api/src/services/integrations/PlanetScaleDiscoveryService.ts
+++ b/apps/api/src/services/integrations/PlanetScaleDiscoveryService.ts
@@ -26,7 +26,7 @@ import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/
 import { parseBase64Aes256GcmKey } from "@/platform/Crypto"
 import { Env } from "@/platform/Env"
 import { buildScrapeAuthHeaders } from "@/services/auth/scrape-auth"
-import { validateExternalUrlSync } from "@/http/url-validator"
+import { validateExternalUrlResult } from "@/http/url-validator"
 import { decodeDiscoveryConfig } from "./planetscale/discovery-config"
 import {
 	PlanetScaleOAuthService,
@@ -143,9 +143,7 @@ export const subTargetsFromGroup = (group: {
 	const dropped: Array<string> = []
 	for (const hostPort of group.targets) {
 		const url = `${scheme}://${hostPort}${path}`
-		try {
-			validateExternalUrlSync(url)
-		} catch {
+		if (Result.isFailure(validateExternalUrlResult(url))) {
 			dropped.push(url)
 			continue
 		}
diff --git a/apps/api/src/services/integrations/vcs/vendor/github/GithubProvider.ts b/apps/api/src/services/integrations/vcs/vendor/github/GithubProvider.ts
index 22ae3ca4a..9bc5b748a 100644
--- a/apps/api/src/services/integrations/vcs/vendor/github/GithubProvider.ts
+++ b/apps/api/src/services/integrations/vcs/vendor/github/GithubProvider.ts
@@ -18,6 +18,7 @@ import {
 	VcsWebhookSignatureError,
 } from "@maple/domain/http"
 import { Clock, Context, Effect, Layer, Match, Option, Redacted, Schema } from "effect"
+import { parseUrlWithBase } from "@maple/domain/url"
 import { Env } from "@/platform/Env"
 import type { VcsProviderClient, VcsWebhookRequest } from "@/services/integrations/vcs/VcsProviderClient"
 import { QUEUE_MESSAGE_LIMIT_BYTES } from "@/services/integrations/vcs/VcsSyncQueue"
@@ -206,11 +207,10 @@ const finiteOrNull = (value: number) => (Number.isFinite(value) ? value : null)
 // dashboard renders with an initials fallback.
 const githubAvatarUrl = (htmlUrl: string, login: string | null): string | null => {
 	if (!login) return null
-	try {
-		return new URL(`/${encodeURIComponent(login)}.png?size=64`, htmlUrl).href
-	} catch {
-		return null
-	}
+	return Option.match(parseUrlWithBase(`/${encodeURIComponent(login)}.png?size=64`, htmlUrl), {
+		onNone: () => null,
+		onSome: (url) => url.href,
+	})
 }
 
 const installationReason = (action: string): VcsInstallationSyncReason | null => {
diff --git a/apps/api/src/services/integrations/vcs/vendor/github/github-hosts.ts b/apps/api/src/services/integrations/vcs/vendor/github/github-hosts.ts
index d63d87a89..4f938564d 100644
--- a/apps/api/src/services/integrations/vcs/vendor/github/github-hosts.ts
+++ b/apps/api/src/services/integrations/vcs/vendor/github/github-hosts.ts
@@ -1,12 +1,5 @@
-import { Option, Schema } from "effect"
-
-/**
- * A string to a `URL`, or `Option.none` when it is not one — the same shape and
- * the same reasoning as `parsePullRequestUrl`: the schema reports the failure as
- * a value rather than a thrown exception, and `decodeUnknownOption` keeps this
- * synchronous and total, so it stays a plain function every caller can use.
- */
-const decodeUrl = Schema.decodeUnknownOption(Schema.URLFromString)
+import { Option } from "effect"
+import { parseUrl } from "@maple/domain/url"
 
 const PUBLIC_GITHUB_WEB = "https://github.com"
 
@@ -21,7 +14,7 @@ const PUBLIC_GITHUB_WEB = "https://github.com"
  * GitHub splits the two across `api.github.com` and `github.com`.
  */
 export const githubWebBaseUrl = (apiBaseUrl: string): string => {
-	const decoded = decodeUrl(apiBaseUrl.trim())
+	const decoded = parseUrl(apiBaseUrl.trim())
 	if (Option.isNone(decoded)) return PUBLIC_GITHUB_WEB
 	const url = decoded.value
 
diff --git a/apps/api/src/worker.ts b/apps/api/src/worker.ts
index b296a4bb3..b268fcee6 100644
--- a/apps/api/src/worker.ts
+++ b/apps/api/src/worker.ts
@@ -2,6 +2,7 @@
 import type { MessageBatch, ScheduledController } from "@cloudflare/workers-types"
 import * as MapleCloudflareSDK from "@maple-dev/effect-sdk/cloudflare"
 import { ANTICIPATED_ERROR_IDENTIFIERS } from "@maple/domain/anticipated-errors"
+import { urlPathname } from "@maple/domain/url"
 import { MCP_ANTICIPATED_ERROR_IDENTIFIERS } from "./mcp/expected-failures"
 import {
 	layerFromEnvRecord,
@@ -231,22 +232,12 @@ const runInternalRpc = async (
 	throw new Error("RPC method failed with an unexpected cause")
 }
 
-const isMcpPost = (request: Request): boolean => {
-	if (request.method !== "POST") return false
-	try {
-		return new URL(request.url).pathname === "/mcp"
-	} catch {
-		return false
-	}
-}
+const isMcpPost = (request: Request): boolean =>
+	request.method === "POST" && urlPathname(request.url) === "/mcp"
 
 const isV2Request = (request: Request): boolean => {
-	try {
-		const pathname = new URL(request.url).pathname
-		return pathname === "/v2" || pathname.startsWith("/v2/")
-	} catch {
-		return false
-	}
+	const pathname = urlPathname(request.url)
+	return pathname === "/v2" || pathname.startsWith("/v2/")
 }
 
 /**
@@ -255,14 +246,8 @@ const isV2Request = (request: Request): boolean => {
  * bootstrap-safe also lets a cold isolate report health when an unrelated
  * application binding is unavailable.
  */
-const isHealthRequest = (request: Request): boolean => {
-	if (request.method !== "GET") return false
-	try {
-		return new URL(request.url).pathname === "/health"
-	} catch {
-		return false
-	}
-}
+const isHealthRequest = (request: Request): boolean =>
+	request.method === "GET" && urlPathname(request.url) === "/health"
 
 const healthResponse = (): Response =>
 	new Response("OK", {
diff --git a/packages/domain/package.json b/packages/domain/package.json
index d701fc73f..48f1b9bc0 100644
--- a/packages/domain/package.json
+++ b/packages/domain/package.json
@@ -23,6 +23,7 @@
 		"./recommendations": "./src/recommendations.ts",
 		"./setup-audit": "./src/setup-audit.ts",
 		"./system-agents": "./src/system-agents.ts",
+		"./url": "./src/url.ts",
 		"./tinybird-project-sync": "./src/tinybird/project-sync.ts",
 		"./warehouse-queries": "./src/warehouse-queries.ts",
 		"./tinybird": "./src/tinybird/index.ts",
diff --git a/packages/domain/src/http/pull-request-ref.ts b/packages/domain/src/http/pull-request-ref.ts
index 9a11b2cdc..1a2e59b47 100644
--- a/packages/domain/src/http/pull-request-ref.ts
+++ b/packages/domain/src/http/pull-request-ref.ts
@@ -1,4 +1,5 @@
-import { Option, Schema } from "effect"
+import { Option } from "effect"
+import { parseUrl } from "../url"
 
 /**
  * Parsing the two string forms that tie a pull request to an issue: a PR URL
@@ -22,16 +23,6 @@ export interface ParsedPullRequestUrl {
 	readonly url: string
 }
 
-/**
- * A string to a `URL`, or `Option.none` when it is not one.
- *
- * `Schema.URLFromString` rather than a `new URL(...)` in a `try`: the schema is
- * the Effect-level primitive for exactly this, it reports the failure as a value
- * instead of a thrown exception, and `decodeUnknownOption` keeps these functions
- * synchronous and total — which is what lets them stay plain predicates that the
- * webhook path, the HTTP handler, and the tests can all call directly.
- */
-const decodeUrl = Schema.decodeUnknownOption(Schema.URLFromString)
 
 // GitHub PR URLs, and only those, since `VcsProviderId` has no other member.
 // `/files`, `/commits`, and `#discussion_r…` suffixes are common in a pasted
@@ -50,7 +41,7 @@ export const parsePullRequestUrl = (input: string): ParsedPullRequestUrl | null
 	const trimmed = input.trim()
 	if (trimmed.length === 0) return null
 
-	const decoded = decodeUrl(trimmed)
+	const decoded = parseUrl(trimmed)
 	if (Option.isNone(decoded)) return null
 	const parsed = decoded.value
 
@@ -104,7 +95,7 @@ export const extractIssueIdsFromText = (text: string, appBaseUrl: string): Reado
 	// `issueLinkUrl` emits in every notification and what the issue page's
 	// copy-link control puts on the clipboard, so it is the form that actually
 	// shows up in PR bodies.
-	const appOrigin = Option.map(decodeUrl(appBaseUrl), (url) => url.origin.toLowerCase())
+	const appOrigin = Option.map(parseUrl(appBaseUrl), (url) => url.origin.toLowerCase())
 	if (Option.isSome(appOrigin)) {
 		const origin = appOrigin.value
 		const urlPattern = new RegExp(`https?://[^\\s<>"')\\]]*/errors/issues/(${uuid})`, "gi")
@@ -112,7 +103,7 @@ export const extractIssueIdsFromText = (text: string, appBaseUrl: string): Reado
 			const id = match[1]
 			if (id === undefined) continue
 			// The regex can match a URL on any host; only this deployment's counts.
-			const matchedOrigin = Option.map(decodeUrl(match[0]), (url) => url.origin.toLowerCase())
+			const matchedOrigin = Option.map(parseUrl(match[0]), (url) => url.origin.toLowerCase())
 			if (Option.isNone(matchedOrigin) || matchedOrigin.value !== origin) continue
 			found.add(id.toLowerCase())
 		}
diff --git a/packages/domain/src/url.test.ts b/packages/domain/src/url.test.ts
new file mode 100644
index 000000000..1530c5274
--- /dev/null
+++ b/packages/domain/src/url.test.ts
@@ -0,0 +1,51 @@
+import { Option } from "effect"
+import { describe, expect, it } from "vitest"
+
+import { parseUrl, parseUrlWithBase, urlPathname } from "./url"
+
+describe("parseUrl", () => {
+	it("decodes an absolute URL", () => {
+		const parsed = parseUrl("https://api.example.com/probe?x=1")
+		expect(Option.isSome(parsed)).toBe(true)
+		expect(Option.getOrThrow(parsed).hostname).toBe("api.example.com")
+	})
+
+	it.each(["", "   ", "not a url", "http://", "/relative/only"])(
+		"is absent rather than throwing for %s",
+		(raw) => {
+			expect(Option.isNone(parseUrl(raw))).toBe(true)
+		},
+	)
+})
+
+describe("parseUrlWithBase", () => {
+	it("resolves a relative target against its base", () => {
+		const resolved = parseUrlWithBase("/avatar.png?size=64", "https://github.acme.internal/x/y")
+		expect(Option.getOrThrow(resolved).href).toBe("https://github.acme.internal/avatar.png?size=64")
+	})
+
+	it("keeps an absolute target", () => {
+		const resolved = parseUrlWithBase("https://other.example.com/z", "https://api.example.com")
+		expect(Option.getOrThrow(resolved).href).toBe("https://other.example.com/z")
+	})
+
+	it("is absent when the base is not a URL", () => {
+		expect(Option.isNone(parseUrlWithBase("/a", "not a url"))).toBe(true)
+	})
+
+	it("is absent when the pair does not resolve", () => {
+		expect(Option.isNone(parseUrlWithBase("http://", "https://api.example.com"))).toBe(true)
+	})
+})
+
+describe("urlPathname", () => {
+	it("reads the path of a request URL", () => {
+		expect(urlPathname("https://api.example.com/v2/traces?limit=1")).toBe("/v2/traces")
+	})
+
+	// The shape the request predicates rely on: no path matches no route, which
+	// is what their `catch { return false }` blocks used to spell out.
+	it("is empty for an unparseable URL", () => {
+		expect(urlPathname("not a url")).toBe("")
+	})
+})
diff --git a/packages/domain/src/url.ts b/packages/domain/src/url.ts
new file mode 100644
index 000000000..5c9bf6500
--- /dev/null
+++ b/packages/domain/src/url.ts
@@ -0,0 +1,45 @@
+import { Option, Schema } from "effect"
+
+/**
+ * URL parsing as a value, shared so no caller has to reach for `new URL(...)` in
+ * a `try`.
+ *
+ * `Schema.URLFromString` is the Effect-level primitive for this: it reports the
+ * failure as a value instead of a thrown exception, and `decodeUnknownOption`
+ * keeps the result synchronous and total, so these stay plain functions that a
+ * predicate, an HTTP handler and a test can all call directly. A thrown
+ * `TypeError` is invisible to the type system, and the `catch` that answers it
+ * flattens "not a URL" together with every other failure in the block.
+ */
+const decodeUrl = Schema.decodeUnknownOption(Schema.URLFromString)
+
+/** A string to a `URL`, or `Option.none` when it is not one. */
+export const parseUrl = (input: string): Option.Option<URL> => decodeUrl(input)
+
+/**
+ * A string to a `URL`, resolved against `base`, or `Option.none` when the pair
+ * does not make one.
+ *
+ * The relative form of {@link parseUrl}. `Schema.URLFromString` takes no base,
+ * so this is the one place the constructor is called — kept total by checking
+ * the base first and treating a rejected pair as absence, the same answer the
+ * absolute form gives.
+ */
+export const parseUrlWithBase = (input: string, base: URL | string): Option.Option<URL> => {
+	const resolvedBase = typeof base === "string" ? parseUrl(base) : Option.some(base)
+	if (Option.isNone(resolvedBase)) return Option.none()
+	// Guarded by `canParse`, so the constructor cannot throw — the same total
+	// contract the schema gives for the absolute form.
+	if (!URL.canParse(input, resolvedBase.value)) return Option.none()
+	return Option.some(new URL(input, resolvedBase.value))
+}
+
+/**
+ * The pathname of a URL, or `""` when the string is not one.
+ *
+ * The shape every request predicate wants: an unparseable URL has no path, so it
+ * matches no route, which is what each of those `catch { return false }` blocks
+ * was spelling out by hand.
+ */
+export const urlPathname = (input: string): string =>
+	Option.match(parseUrl(input), { onNone: () => "", onSome: (url) => url.pathname })
diff --git a/packages/query-engine/src/execution/backend.ts b/packages/query-engine/src/execution/backend.ts
index a581275d2..91fd0c6d5 100644
--- a/packages/query-engine/src/execution/backend.ts
+++ b/packages/query-engine/src/execution/backend.ts
@@ -9,6 +9,9 @@
  *                        env-level self-hosted read endpoint
  * - `chdb`             — the embedded chDB engine behind the local `maple` binary
  */
+import { Option } from "effect"
+import { parseUrl } from "@maple/domain/url"
+
 export type WarehouseBackendKind = "tinybird" | "tinybird-gateway" | "clickhouse" | "chdb"
 
 export interface TinybirdBackendConfig {
@@ -54,11 +57,10 @@ export interface WarehouseTargetIdentity {
 const hostOf = (urlOrHost: string): string => {
 	const trimmed = urlOrHost.trim()
 	if (trimmed === "") return ""
-	try {
-		return new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`).host
-	} catch {
-		return trimmed
-	}
+	return Option.match(parseUrl(trimmed.includes("://") ? trimmed : `https://${trimmed}`), {
+		onNone: () => trimmed,
+		onSome: (url) => url.host,
+	})
 }
 
 export const warehouseTargetIdentity = (config: ResolvedWarehouseConfig): WarehouseTargetIdentity =>