@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/kernel/packs/compile.test.ts

@@ -11,7 +11,7 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { RECOVERY_CLI_PREFIX } from "../../constants.js";
 import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
 import type { PragmaRuntime } from "../runtime/types.js";
-import { compilePack } from "./compile.js";
+import { compileListable, compilePack, compileStoryModule } from "./compile.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import { parsePackDefinition } from "./schema.js";
 import type { PackDefinition, PackRow } from "./types.js";
@@ -383,3 +383,224 @@ describe("pack compiler — SPARQL fetch path (PROTECTED)", () => {
     expect(data.totalCount).toBe(2);
   });
 });
+
+/**
+ * The listing a story contributes to the MCP resource surface is DERIVED from
+ * the types its lookup already names — the story author writes the type set
+ * once, for the name resolve, and the resource listing reads that same
+ * declaration. Nothing to keep in sync because there is nothing written twice.
+ */
+describe("declared listing (derived from the lookup's types)", () => {
+  it("derives one collection per declared type, unweighted types at 1", () => {
+    expect(
+      compileListable({
+        noun: "gadget",
+        lookup: { by: "ex:name", types: ["ex:Widget", "ex:Part"] },
+      }),
+    ).toEqual({
+      sources: [
+        { type: "ex:Widget", as: "collection", weight: 1 },
+        { type: "ex:Part", as: "collection", weight: 1 },
+      ],
+    });
+  });
+
+  it("carries a declared weight onto the type it names", () => {
+    const listable = compileListable({
+      noun: "gadget",
+      lookup: {
+        by: "ex:name",
+        types: ["ex:Widget", "ex:Part"],
+        weights: { "ex:Part": 0.6 },
+      },
+    });
+    expect(listable?.sources.map((s) => s.weight)).toEqual([1, 0.6]);
+  });
+
+  it("declares nothing for a list-only noun (it addresses no class)", () => {
+    expect(
+      compileListable({ noun: "gadget", list: { query: "", columns: [] } }),
+    ).toBeUndefined();
+  });
+
+  it("carries the listing onto the compiled module, beside its verbs", () => {
+    const module = compileStoryModule(
+      { noun: "gadget", lookup: { by: "ex:name", type: "ex:Widget" } },
+      distributionSource("t"),
+      PREFIXES,
+    );
+    expect(module.story).toBe(true);
+    expect(module.mcpListable?.sources).toEqual([
+      { type: "ex:Widget", as: "collection", weight: 1 },
+    ]);
+  });
+});
+
+describe("weights validation (a weight that can never apply is rejected)", () => {
+  it("accepts a weight naming a type the lookup addresses", () => {
+    const definition = {
+      noun: "gadget",
+      lookup: {
+        by: "ex:name",
+        types: ["ex:Widget", "ex:Part"],
+        weights: { "ex:Part": 0.6 },
+      },
+    };
+    expect(parsePackDefinition(definition, "t")).toEqual(definition);
+  });
+
+  it("REJECTS a weight naming a type the lookup does not address", () => {
+    // A silent no-op is how a weight that never applied survives review: the
+    // type gets renamed, the weight stays pointed at the old name, and nothing
+    // says so — the ranking simply stops changing.
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "gadget",
+          lookup: {
+            by: "ex:name",
+            types: ["ex:Widget"],
+            weights: { "ex:Gone": 0.6 },
+          },
+        },
+        "t",
+      ),
+    ).toThrow(/ex:Gone/);
+  });
+
+  it("REJECTS a weight outside 0–1", () => {
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "gadget",
+          lookup: {
+            by: "ex:name",
+            type: "ex:Widget",
+            weights: { "ex:Widget": 2 },
+          },
+        },
+        "t",
+      ),
+    ).toThrow();
+  });
+});
+
+describe("nameFallback validation (a derived name needs a class to vouch for it)", () => {
+  it("accepts the fallback beside a class constraint", () => {
+    const definition = {
+      noun: "gadget",
+      lookup: { by: "ex:name", nameFallback: "iri", type: "ex:Widget" },
+    };
+    expect(parsePackDefinition(definition, "t")).toEqual(definition);
+  });
+
+  it("REJECTS the fallback with no class constraint", () => {
+    // Without one there is no triple bounding `?uri`, so the derived-name
+    // population would be scanned over the whole graph — and a derived name is
+    // only as trustworthy as the class vouching for the entity it came from.
+    expect(() =>
+      parsePackDefinition(
+        { noun: "gadget", lookup: { by: "ex:name", nameFallback: "iri" } },
+        "t",
+      ),
+    ).toThrow(/nameFallback/);
+  });
+});
+
+describe("filter vocabulary validation (where a value-free filter's values live)", () => {
+  const listShape = {
+    query: "SELECT ?uri ?kind WHERE { ?uri a ex:Widget ; ex:kind ?kind }",
+    columns: [{ field: "uri" }],
+  };
+
+  it("accepts a vocabulary SELECT on a value-free filter", () => {
+    const definition = {
+      noun: "widget",
+      list: {
+        ...listShape,
+        filters: [
+          {
+            param: "kind",
+            variable: "kind",
+            vocabulary: { query: "SELECT ?kind WHERE { ?k a ex:Kind }" },
+          },
+        ],
+      },
+    };
+    expect(parsePackDefinition(definition, "t")).toEqual(definition);
+  });
+
+  it("REJECTS a vocabulary beside a declared `values` set", () => {
+    // A declared set IS the vocabulary — the filter projects it as an enum and
+    // canonicalizes against it. A second, graph-read one alongside is a silent
+    // no-op at best and a disagreement at worst.
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "widget",
+          list: {
+            ...listShape,
+            filters: [
+              {
+                param: "kind",
+                variable: "kind",
+                values: ["a", "b"],
+                vocabulary: { query: "SELECT ?kind WHERE { ?k a ex:Kind }" },
+              },
+            ],
+          },
+        },
+        "t",
+      ),
+    ).toThrow(/mutually exclusive/);
+  });
+
+  it("REJECTS a vocabulary query that is not a SELECT", () => {
+    expect(() =>
+      parsePackDefinition(
+        {
+          noun: "widget",
+          list: {
+            ...listShape,
+            filters: [
+              {
+                param: "kind",
+                variable: "kind",
+                vocabulary: { query: "ASK { ?k a ex:Kind }" },
+              },
+            ],
+          },
+        },
+        "t",
+      ),
+    ).toThrow(/SELECT/);
+  });
+});
+
+describe("compileListable — absolute IRIs reach the prefixed contract", () => {
+  it("compacts an absolute lookup type, and its weight key with it", () => {
+    // `PackLookup.type`/`types` accept a prefixed name OR an absolute IRI, but
+    // the listing is keyed on the index's prefixed types. Verbatim, such a story
+    // compiled clean and then matched no class and no weight.
+    const listable = compileListable({
+      noun: "widget",
+      lookup: {
+        by: "ds:name",
+        types: ["https://ds.canonical.com/Component", "ds:Pattern"],
+        weights: { "https://ds.canonical.com/Component": 0.4 },
+      },
+    } as PackDefinition);
+
+    expect(listable?.sources.map((s) => s.type)).toEqual([
+      "ds:Component",
+      "ds:Pattern",
+    ]);
+    // The weight followed its type through the same compaction, so it still
+    // applies — keying it on the raw IRI would have silently dropped it.
+    const component = listable?.sources.find((s) => s.type === "ds:Component");
+    expect(component?.weight).toBe(0.4);
+    expect(listable?.sources.find((s) => s.type === "ds:Pattern")?.weight).toBe(
+      1,
+    );
+  });
+});

package/src/kernel/packs/compile.ts

@@ -15,9 +15,16 @@
  */
 
 import { BIN_NAME } from "../../constants.js";
-import type { PragmaRuntime } from "../runtime/types.js";
+import { compactUri, DEFAULT_PREFIX_MAP } from "../render/index.js";
+import type { PragmaRuntime } from "../runtime/index.js";
 import { asVerb } from "../spec/asVerb.js";
-import type { DisclosureSpec, ParamSpec, VerbSpec } from "../spec/types.js";
+import type {
+  CapabilityModule,
+  DisclosureSpec,
+  McpListable,
+  ParamSpec,
+  VerbSpec,
+} from "../spec/types.js";
 import {
   listFormatters,
   lookupFormatters,
@@ -107,6 +114,83 @@ export function compilePack(
   return verbs;
 }
 
+/**
+ * Derive a story's MCP resource listing from the types its lookup addresses.
+ *
+ * ZERO new authoring: a read story ALREADY declares its type set
+ * (`lookup.type` / `lookup.types`) because that is what its name resolve is
+ * constrained by, so the slice of the index the noun contributes to the listing
+ * IS that declaration read a second time by a different reader — never written
+ * a second time by the author. Each type contributes ONE collection entry (its
+ * class entry, carrying the instance count); the individuals stay reachable
+ * through the `{+uri}` template and its autocomplete.
+ *
+ * Returns `undefined` for a story with no lookup (a list-only noun addresses no
+ * class, so it can name no slice).
+ *
+ * @param definition - A validated pack definition.
+ * @returns Its declared listing, or `undefined` when it declares no types.
+ */
+export function compileListable(
+  definition: PackDefinition,
+): McpListable | undefined {
+  const lookup = definition.lookup;
+  if (!lookup) return undefined;
+  const types = lookup.types ?? (lookup.type ? [lookup.type] : []);
+  if (types.length === 0) return undefined;
+  // `PackLookup.type`/`types` accept a prefixed name OR an absolute IRI, but the
+  // listing is keyed on the index's PREFIXED types. Copied verbatim, a lookup
+  // legitimately constrained to `https://…/Widget` compiles clean and then
+  // matches no class and no weight — a story that is valid everywhere else and
+  // silently contributes nothing here. Compacted against the same map
+  // `resolveUri` expands with, so the two directions agree.
+  const compact = (type: string): string =>
+    compactUri(type, DEFAULT_PREFIX_MAP);
+  const weights = Object.fromEntries(
+    Object.entries(lookup.weights ?? {}).map(([type, weight]) => [
+      compact(type),
+      weight,
+    ]),
+  );
+  return {
+    sources: types.map(compact).map((type) => ({
+      type,
+      as: "collection" as const,
+      // Unlisted types weigh 1 — the default is "as important as any other",
+      // so a story that declares no weights needs no weights.
+      weight: weights[type] ?? 1,
+    })),
+  };
+}
+
+/**
+ * Compile a story into the capability module that carries it.
+ *
+ * The ONE place a {@link PackDefinition} becomes a {@link CapabilityModule} —
+ * the distribution's static stories and the dynamic (config/package) ones come
+ * through here alike, so a module-level projection derived from the story
+ * (today: {@link compileListable}) cannot reach one tier and miss the other.
+ *
+ * @param definition - A validated pack definition.
+ * @param source - Where the definition came from, for diagnostics.
+ * @param prefixes - The merged prefix map used for display compaction.
+ * @returns The module: the compiled verbs plus the story's module-level data.
+ */
+export function compileStoryModule(
+  definition: PackDefinition,
+  source: StorySource,
+  prefixes: Readonly<Record<string, string>>,
+): CapabilityModule {
+  const listable = compileListable(definition);
+  return {
+    name: definition.noun,
+    story: true,
+    verbs: compilePack(definition, source, prefixes),
+    colophon: definition.colophon,
+    ...(listable ? { mcpListable: listable } : {}),
+  };
+}
+
 /** Presentation facts for one compiled list-shaped verb. */
 interface ListVerbMeta {
   readonly noun: string;
@@ -287,9 +371,15 @@ function projectFilters(
         name: filter.param,
         doc,
         values: [...filter.values],
+        repeatable: true,
       } satisfies ParamSpec;
     }
-    return { kind: "string", name: filter.param, doc } satisfies ParamSpec;
+    return {
+      kind: "string",
+      name: filter.param,
+      doc,
+      repeatable: true,
+    } satisfies ParamSpec;
   });
 }
 

package/src/kernel/packs/disclosure.ts

@@ -18,8 +18,8 @@
  */
 
 import { DETAIL_LEVELS } from "../../constants.js";
-import { resolveDetail } from "../render/disclosure.js";
-import type { PragmaRuntime } from "../runtime/types.js";
+import { resolveDetail } from "../render/index.js";
+import type { PragmaRuntime } from "../runtime/index.js";
 import type { PackDisclosure, PackExpand, PackField } from "./types.js";
 
 /** The canonical level names, lowest → highest. */

package/src/kernel/packs/graphql/buildLookupDocument.ts

@@ -23,7 +23,7 @@
  * stays off the storeless fast path).
  */
 
-import { PragmaError } from "../../error/PragmaError.js";
+import { PragmaError } from "../../error/index.js";
 import { activeExpands, activeFields } from "./../sparql/buildLookupQuery.js";
 import type {
   PackExpand,

package/src/kernel/packs/graphql/fetchGraphqlLookup.ts

@@ -14,9 +14,8 @@
  * composed only from validated pack terms and compiled schema names.
  */
 
-import { PragmaError } from "../../error/PragmaError.js";
-import { cliRecovery } from "../../error/recovery.js";
-import type { PragmaRuntime } from "../../runtime/types.js";
+import { cliRecovery, PragmaError } from "../../error/index.js";
+import type { PragmaRuntime } from "../../runtime/index.js";
 import type { PackChildRow, PackEntity, PackLookup } from "../types.js";
 import {
   buildLookupDocument,
@@ -72,7 +71,7 @@ export async function fetchGraphqlLookup(
     // ontology). That is a runtime not-found, not an unavailable store (exit 3).
     throw new PragmaError({
       code: "ENTITY_NOT_FOUND",
-      message: `Could not resolve <${entityUri}> — its rdf:type may be missing from the ontology.`,
+      message: `Cannot resolve <${entityUri}> — its rdf:type may be missing from the ontology.`,
       recovery: cliRecovery(
         `graph inspect ${entityUri}`,
         "Inspect the entity's triples to check its rdf:type.",

package/src/kernel/packs/graphql/index.ts

@@ -0,0 +1,20 @@
+/**
+ * The GraphQL lookup path — what a `source: "graphql"` pack story executes
+ * once SPARQL has resolved its name to an entity IRI.
+ *
+ * The three files here are one function split for testability, not three
+ * services: the naming rules derive schema field names from the RDF properties
+ * a pack declares, the document generator turns a lookup declaration plus
+ * those names into the single query to run, and the fetcher executes it and
+ * unwraps the Relay envelope into the same flat entity shape the SPARQL path
+ * produces. Only the last of those is something a caller does.
+ *
+ * So the barrel is one export, and the narrowness is the point. The document
+ * generator's contract is that the entity IRI travels as a query VARIABLE and
+ * never as interpolated text, and that a document is composed only from
+ * validated pack terms and compiled schema names. Handing out the generator on
+ * its own would hand out a way to build a document and execute it by some
+ * other route; handing out the fetcher hands out the guarantee with it.
+ */
+
+export { fetchGraphqlLookup } from "./fetchGraphqlLookup.js";

package/src/kernel/packs/index.ts

@@ -0,0 +1,40 @@
+/**
+ * The packs domain — declared stories become runnable verbs.
+ *
+ * One pipeline runs end to end inside this folder: a JSON pack declaration is
+ * parsed and validated, compiled into `VerbSpec`s, and given run bodies that
+ * resolve entities out of the graph and formatters that render them. The
+ * intermediate stages — the schema parser, the query/render/run-body builders,
+ * the entity resolver, the sampler, the glob expander — are steps in that
+ * pipeline, not services, and they stay off this barrel: a caller reaching for
+ * one of them is a caller reassembling the pipeline by hand, and the whole
+ * point of compiling a pack once is that nobody has to.
+ *
+ * What crosses the boundary is the pipeline's ends and the contracts naming
+ * them. `compilePack` is the entry the distribution and the config-story path
+ * both take. `validateStories` and `loadEffectiveModules` are the two ways
+ * third-party stories are admitted — the first screens records and reports
+ * every problem (which is how `doctor` reports a story the CLI drops rather
+ * than letting it vanish), the second is the full load the MCP server and the
+ * `capabilities` verb take. `resolvePackDetail` and `resolveUri` are the two
+ * decisions a pack's own reads defer to the runtime, and `verbKey` is the
+ * identity function every surface keys a verb by.
+ *
+ * `loadEffectiveModules` reads config and the answering pack behind DYNAMIC
+ * imports so a bare `--help` never pays for either; consumers reach it lazily
+ * today for exactly that reason, and routing it through this barrel statically
+ * would put the config reader back on the fast path.
+ */
+
+export type { StoryProblem } from "./collect.js";
+export { loadEffectiveModules, validateStories } from "./collect.js";
+export { compilePack } from "./compile.js";
+export { resolvePackDetail } from "./disclosure.js";
+export { resolveUri } from "./iri.js";
+export type {
+  PackDefinition,
+  PackRow,
+  StorySource,
+} from "./types.js";
+export { distributionSource } from "./types.js";
+export { verbKey } from "./uniqueness.js";

package/src/kernel/packs/iri.test.ts

@@ -0,0 +1,73 @@
+/**
+ * URI resolution — what it accepts, and what it says when it refuses.
+ *
+ * Both halves matter and only one was covered. `resolveUri` is reached by every
+ * read (`graph inspect`, every pack lookup, the `pragma:{+uri}` resource), so
+ * its diagnostic is the sentence a user or an agent actually has to act on.
+ * Nothing asserted that sentence, which is how it came to quote a string the
+ * caller never typed.
+ */
+
+import { describe, expect, it } from "vitest";
+import { resolveUri } from "./iri.js";
+
+const DS = "https://ds.canonical.com/";
+const PREFIXES: Readonly<Record<string, string>> = { ds: DS };
+
+/** Run `resolveUri` and hand back whatever it threw, for assertion. */
+function refusal(uri: string): { code?: string; message?: string } {
+  try {
+    resolveUri(uri, PREFIXES);
+    throw new Error(`expected "${uri}" to be refused`);
+  } catch (error) {
+    return error as { code?: string; message?: string };
+  }
+}
+
+describe("resolveUri", () => {
+  it("resolves the plain forms", () => {
+    expect(resolveUri("ds:Component", PREFIXES)).toBe(`${DS}Component`);
+    expect(resolveUri(`${DS}Component`, PREFIXES)).toBe(`${DS}Component`);
+  });
+
+  it("accepts a percent-encoded prefixed name", () => {
+    // A client that encodes the URI it puts in a `pragma:{+uri}` read is not
+    // doing anything wrong; refusing it made the resource surface reject its
+    // own advertised identifiers.
+    expect(resolveUri("ds%3AComponent", PREFIXES)).toBe(`${DS}Component`);
+  });
+
+  it("names the URI the CALLER typed, not the expansion", () => {
+    // The safety check runs on the expanded IRI — it has to — but the message
+    // is for whoever typed the input, and they never typed the expansion.
+    const error = refusal("ds:my component");
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error.message).toContain("ds:my component");
+    expect(error.message).not.toContain(DS);
+  });
+
+  it("refuses malformed percent input as INVALID_INPUT, not a URIError", () => {
+    // `decodeURIComponent` throws `URIError` on a truncated escape. Escaping as
+    // a raw TypeError would surface as an internal fault rather than the
+    // caller's bad input.
+    const error = refusal("%E0%A4%A");
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error).not.toBeInstanceOf(URIError);
+    expect(error.message).toContain("%E0%A4%A");
+  });
+
+  it("refuses an unknown prefix and offers the ones it knows", () => {
+    const error = refusal("nope:Thing") as {
+      code?: string;
+      validOptions?: string[];
+    };
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error.validOptions).toContain("ds");
+  });
+
+  it("refuses a payload that would break out of the <iri> token", () => {
+    // The injection guard, asserted here rather than only through a verb.
+    const error = refusal('ds:x> } INSERT { ?s ?p "y" } #');
+    expect(error.code).toBe("INVALID_INPUT");
+  });
+});

package/src/kernel/packs/iri.ts

@@ -7,8 +7,7 @@
  * before it can be interpolated into a generated `<iri>` query token.
  */
 
-import { PragmaError } from "../error/PragmaError.js";
-import { cliRecovery } from "../error/recovery.js";
+import { cliRecovery, PragmaError } from "../error/index.js";
 
 /** Characters not allowed inside a SPARQL `<IRI>`. */
 const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
@@ -27,6 +26,11 @@ export function isEmbeddableIri(value: string): boolean {
 /**
  * Resolve a prefixed or absolute URI to its full form.
  *
+ * A value that fails to resolve and carries a `%` is retried once decoded, so a
+ * client that percent-encodes the URI it addresses (`ds%3AComponent`) is served
+ * rather than rejected. Every diagnostic names the value the CALLER supplied —
+ * the safety check runs on the expansion, but nobody typed the expansion.
+ *
  * @param uri - A full or prefixed URI string.
  * @param prefixes - The store's merged prefix→namespace map.
  * @returns The fully expanded URI.
@@ -36,9 +40,33 @@ export function resolveUri(
   uri: string,
   prefixes: Readonly<Record<string, string>>,
 ): string {
+  const direct = tryResolveUri(uri, prefixes);
+  if (typeof direct === "string") return direct;
+
+  const decoded = uri.includes("%") ? decodeOnce(uri) : undefined;
+  if (decoded !== undefined && decoded !== uri) {
+    const viaDecoded = tryResolveUri(decoded, prefixes);
+    if (typeof viaDecoded === "string") return viaDecoded;
+  }
+
+  // Report the input as given, never the decoded or expanded form.
+  throw direct;
+}
+
+/**
+ * One resolution attempt: the expanded IRI, or the error describing `uri`.
+ *
+ * @param uri - The candidate URI, as the caller wrote it.
+ * @param prefixes - The store's merged prefix→namespace map.
+ * @returns The expanded IRI on success, else the PragmaError to report.
+ */
+function tryResolveUri(
+  uri: string,
+  prefixes: Readonly<Record<string, string>>,
+): string | PragmaError {
   const colonIdx = uri.indexOf(":");
   if (colonIdx === -1) {
-    throw PragmaError.invalidInput("uri", uri, {
+    return PragmaError.invalidInput("uri", uri, {
       recovery: {
         message: 'Use a prefixed URI (e.g. "prefix:name") or a full URI.',
       },
@@ -49,16 +77,14 @@ export function resolveUri(
   const namespace = prefixes[prefix];
   if (namespace !== undefined) {
     const resolved = `${namespace}${uri.slice(colonIdx + 1)}`;
-    assertSafeIri(resolved);
-    return resolved;
+    return unsafeIriError(uri, resolved) ?? resolved;
   }
 
   if (ABSOLUTE_IRI_PATTERN.test(uri)) {
-    assertSafeIri(uri);
-    return uri;
+    return unsafeIriError(uri, uri) ?? uri;
   }
 
-  throw PragmaError.invalidInput("prefix", prefix, {
+  return PragmaError.invalidInput("prefix", prefix, {
     validOptions: Object.keys(prefixes),
     recovery: cliRecovery("ontology list", "List known ontology prefixes.", {
       tool: "ontology_list",
@@ -66,11 +92,37 @@ export function resolveUri(
   });
 }
 
-/** @throws PragmaError INVALID_INPUT when the URI contains IRI-breaking characters. */
-function assertSafeIri(uri: string): void {
-  if (UNSAFE_IRI_PATTERN.test(uri)) {
-    throw PragmaError.invalidInput("uri", uri, {
-      recovery: { message: "URI contains characters not allowed in IRIs." },
-    });
+/**
+ * Guard the EXPANSION, name the INPUT: the check is on the IRI that would reach
+ * a query, the message is about the value the caller actually typed.
+ *
+ * @param input - The URI as the caller wrote it.
+ * @param resolved - The expanded IRI the check runs against.
+ * @returns The error when `resolved` carries IRI-breaking characters, else undefined.
+ */
+function unsafeIriError(
+  input: string,
+  resolved: string,
+): PragmaError | undefined {
+  if (!UNSAFE_IRI_PATTERN.test(resolved)) return undefined;
+  return PragmaError.invalidInput("uri", input, {
+    recovery: { message: "URI contains characters not allowed in IRIs." },
+  });
+}
+
+/**
+ * Percent-decode a value, tolerating malformed encodings.
+ *
+ * `decodeURIComponent` throws `URIError` on a stray `%` — a decode ATTEMPT must
+ * never turn a reportable input error into a crash.
+ *
+ * @param value - The possibly percent-encoded value.
+ * @returns The decoded value, or undefined when it cannot be decoded.
+ */
+function decodeOnce(value: string): string | undefined {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return undefined;
   }
 }