@skyramp/mcp 0.3.2 → 0.3.4

package/build/utils/workspaceAuth.d.ts

@@ -1,3 +1,4 @@
+import { type ScopedQueryParams } from "../workspace/queryParamResolution.js";
 /**
  * Reads `.skyramp/workspace.yml`.
  *
@@ -133,20 +134,6 @@ export declare function getWorkspaceAuthConfig(repositoryPath: string): Promise<
 /** True when any workspace service declares api.skipTLSVerify — the SUT serves
  *  self-signed TLS and generated tests must skip cert verification (SKYR-3961). */
 export declare function getWorkspaceSkipTLSVerify(repositoryPath: string): Promise<boolean>;
-/**
- * Resolve api.defaultQueryParams for test generation — query params always
- * attached to every generated request for this service (e.g. RBAC context
- * an authorization layer requires beyond the auth header). Same
- * first-matching-service convention as getWorkspaceAuthConfig (SKYR-4050).
- *
- * Unlike readWorkspaceConfigRaw (which delegates to WorkspaceConfigManager and
- * resolves EXACTLY `<repositoryPath>/.skyramp/workspace.yml`), this walks up
- * from `repositoryPath` to find the nearest `.skyramp/workspace.yml` — both
- * call sites pass a nested test-output directory (e.g. `<repo>/tests/skyramp`),
- * not the repo root, so an exact-match lookup would silently never find the
- * config. Mirrors the sync fs.existsSync walk-up in
- * generateBatchScenarioRestTool.ts.
- */
 /**
  * Walk up from `startDir` to find the nearest `.skyramp/workspace.yml`, checking
  * `startDir` itself first and continuing through every ancestor INCLUDING the
@@ -156,7 +143,20 @@ export declare function getWorkspaceSkipTLSVerify(repositoryPath: string): Promi
  * `existsSync` is injectable for testing; defaults to the real filesystem.
  */
 export declare function findWorkspaceConfigPath(startDir: string, existsSync?: (p: string) => boolean): string | null;
-export declare function getWorkspaceDefaultQueryParams(repositoryPath: string): Promise<Record<string, string> | undefined>;
+/**
+ * Resolve api.defaultQueryParams together with api.queryParamOverrides for test
+ * generation (SKYR-4127). Same first-matching-service convention as
+ * getWorkspaceAuthConfig: the first service declaring EITHER key wins.
+ *
+ * Reads the YAML directly rather than through the Zod schema — the walk-up must
+ * stay cheap, and hand-rolled fixtures routinely omit fields the strict schema
+ * requires. normalizeOverrides therefore validates the override list itself,
+ * once per load rather than per request.
+ *
+ * Returns undefined when no config is found or no service declares either key,
+ * so callers can skip the merge entirely.
+ */
+export declare function getWorkspaceScopedQueryParams(repositoryPath: string): Promise<ScopedQueryParams | undefined>;
 /**
  * Merge workspace-declared default query params into a comma-separated
  * "key=value,key2=value2" queryParams string (the format used by

package/build/utils/workspaceAuth.js

@@ -2,6 +2,7 @@ import * as fs from "fs";
 import path from "path";
 import yaml from "js-yaml";
 import { WorkspaceConfigManager } from "../workspace/workspace.js";
+import { normalizeBaseMap, normalizeOverrides } from "../workspace/queryParamResolution.js";
 import { logger } from "./logger.js";
 /**
  * Reads `.skyramp/workspace.yml`.
@@ -363,20 +364,6 @@ export async function getWorkspaceSkipTLSVerify(repositoryPath) {
         return false;
     return (rawConfig.services ?? []).some((s) => s.api?.skipTLSVerify === true);
 }
-/**
- * Resolve api.defaultQueryParams for test generation — query params always
- * attached to every generated request for this service (e.g. RBAC context
- * an authorization layer requires beyond the auth header). Same
- * first-matching-service convention as getWorkspaceAuthConfig (SKYR-4050).
- *
- * Unlike readWorkspaceConfigRaw (which delegates to WorkspaceConfigManager and
- * resolves EXACTLY `<repositoryPath>/.skyramp/workspace.yml`), this walks up
- * from `repositoryPath` to find the nearest `.skyramp/workspace.yml` — both
- * call sites pass a nested test-output directory (e.g. `<repo>/tests/skyramp`),
- * not the repo root, so an exact-match lookup would silently never find the
- * config. Mirrors the sync fs.existsSync walk-up in
- * generateBatchScenarioRestTool.ts.
- */
 /**
  * Walk up from `startDir` to find the nearest `.skyramp/workspace.yml`, checking
  * `startDir` itself first and continuing through every ancestor INCLUDING the
@@ -398,15 +385,43 @@ export function findWorkspaceConfigPath(startDir, existsSync = fs.existsSync) {
         searchDir = parentDir;
     }
 }
-export async function getWorkspaceDefaultQueryParams(repositoryPath) {
+/**
+ * Resolve api.defaultQueryParams together with api.queryParamOverrides for test
+ * generation (SKYR-4127). Same first-matching-service convention as
+ * getWorkspaceAuthConfig: the first service declaring EITHER key wins.
+ *
+ * Reads the YAML directly rather than through the Zod schema — the walk-up must
+ * stay cheap, and hand-rolled fixtures routinely omit fields the strict schema
+ * requires. normalizeOverrides therefore validates the override list itself,
+ * once per load rather than per request.
+ *
+ * Returns undefined when no config is found or no service declares either key,
+ * so callers can skip the merge entirely.
+ */
+export async function getWorkspaceScopedQueryParams(repositoryPath) {
     const wsConfigPath = findWorkspaceConfigPath(repositoryPath);
     if (!wsConfigPath)
         return undefined;
     try {
         const raw = fs.readFileSync(wsConfigPath, "utf-8");
         const parsed = yaml.load(raw);
-        const svc = parsed?.services?.find((s) => s.api?.defaultQueryParams !== undefined);
-        return svc?.api?.defaultQueryParams;
+        const declaring = (parsed?.services ?? []).filter((s) => s?.api?.defaultQueryParams !== undefined || s?.api?.queryParamOverrides !== undefined);
+        const svc = declaring[0];
+        if (!svc)
+            return undefined;
+        // First-wins is deliberate (same convention as getWorkspaceAuthConfig) —
+        // but silently discarding a later service's config is easy to miss, so
+        // name what's being ignored (Finding 3, SKYR-4127 final review).
+        if (declaring.length > 1) {
+            logger.warning("Multiple services declare defaultQueryParams/queryParamOverrides — using the first, ignoring the rest", {
+                used: svc.serviceName,
+                ignored: declaring.slice(1).map((s) => s.serviceName),
+            });
+        }
+        return {
+            base: normalizeBaseMap(svc.api.defaultQueryParams),
+            overrides: normalizeOverrides(svc.api.queryParamOverrides),
+        };
     }
     catch {
         return undefined;

package/build/workspace/queryParamResolution.d.ts

@@ -0,0 +1,93 @@
+export interface QueryParamOverride {
+    /** picomatch glob matched against the request URL pathname. OpenAPI-style
+     *  `{param}` placeholders are treated as a single-segment wildcard. */
+    pathPattern: string;
+    /**
+     * Known wart (Finding 6, SKYR-4127 final review): `values: {}` is a valid,
+     * deliberately-typed empty map. If its pathPattern is the single most
+     * specific match for a request, it wins and contributes nothing — silently
+     * suppressing a broader override that would otherwise have applied. Not
+     * validated against because an intentionally no-op override (e.g. "no
+     * extra params for this path, unlike its siblings") is a legitimate use.
+     */
+    values: Record<string, string>;
+}
+export interface ScopedQueryParams {
+    /** api.defaultQueryParams — applied to every request for the service. */
+    base: Record<string, string>;
+    /** api.queryParamOverrides — at most one applies to any given request. */
+    overrides: QueryParamOverride[];
+}
+/** Pathname of a full endpoint URL, or undefined if unparseable.
+ *  `endpointURL` is contractually base URL + path, so the result includes any
+ *  base-path prefix: `https://host/api/v1/persons/42` -> `/api/v1/persons/42`.
+ *
+ *  Delegates to the shared helper so this module and the plan guard cannot
+ *  disagree about what an endpointURL's path is — the shared version also
+ *  restores `{param}` placeholders that `new URL()` percent-encodes, which
+ *  patterns are authored with. */
+export declare function extractPathname(endpointURL: string | undefined): string | undefined;
+/** True when a resolved config would contribute no query params at all.
+ *  Both call sites skip the merge entirely in that case, so an empty
+ *  declaration leaves queryParams untouched rather than setting it to an empty
+ *  value. Defined once so the two sites cannot drift on what "empty" means. */
+export declare function contributesNothing(config: ScopedQueryParams): boolean;
+/** Batch-scenario steps carry a bare path that may or may not be rooted. */
+export declare function ensureLeadingSlash(p: string): string;
+/** Rank for most-specific-wins: length of the literal prefix before the first
+ *  wildcard, computed on the ORIGINAL pattern so `{id}` still counts. */
+export declare function patternSpecificity(pathPattern: string): number;
+/**
+ * Validate and coerce the raw `api.queryParamOverrides` value read from YAML.
+ *
+ * The read path in workspaceAuth.ts parses workspace.yml directly rather than
+ * through the Zod schema (the walk-up read must stay cheap), so nothing has
+ * validated this yet. Malformed entries are dropped with a warning instead of
+ * failing generation. Called once per load, not per request.
+ */
+export declare function normalizeOverrides(raw: unknown): QueryParamOverride[];
+/**
+ * Validate and coerce the raw `api.defaultQueryParams` value read from YAML.
+ *
+ * Same reason `normalizeOverrides` exists: this read path deliberately bypasses
+ * the Zod schema, so nothing has checked the shape. Without this, a scalar
+ * declaration (`defaultQueryParams: just-a-string`) is spread by key and yields
+ * one query param per character — `0=j&1=u&2=s&…` sent to the server. A list
+ * behaves the same way, and a map with non-string values would reach
+ * mergeQueryParams* and be dropped there with a less specific warning.
+ *
+ * Anything that is not a plain object of string values degrades to an empty
+ * base map with a warning naming what was found.
+ */
+export declare function normalizeBaseMap(raw: unknown): Record<string, string>;
+/**
+ * Effective query params for one request path: the base map with the single
+ * most-specific matching override layered on top.
+ *
+ * Overrides never merge with each other — at most one wins. Ranking is by
+ * literal prefix length, then total pattern length, then document order.
+ *
+ * Whenever the patterns differ in specificity the result is independent of how
+ * the YAML list is ordered. Document order is only reached when two patterns
+ * tie on BOTH earlier criteria, and reordering the list does change the winner
+ * in that case — which is why a tie emits an ambiguity warning naming both
+ * patterns rather than resolving silently.
+ */
+export declare function resolveQueryParamsForPath(config: ScopedQueryParams, pathname: string): Record<string, string>;
+/** Environment variables this workspace's query params defer to, in declaration
+ *  order and deduplicated (SKYR-4127).
+ *
+ *  These references resolve where the test RUNS, so under Testbot they resolve
+ *  inside the executor container — whose environment is a fixed allowlist. A
+ *  name that never reaches the container resolves to nothing, and an unresolved
+ *  query param is dropped from the request silently, producing a passing test
+ *  that exercised the wrong identity. The executor uses this list to forward
+ *  exactly what the workspace asked for.
+ *
+ *  Deliberately derived from the declarations rather than from the ambient
+ *  environment: nothing is forwarded that workspace.yml did not name.
+ *
+ *  Both maps are read even though `defaultQueryParams` documents itself as
+ *  literal-only — that is a doc contract the core loader does not enforce, and
+ *  a declaration there would otherwise reproduce the original silent failure. */
+export declare function extractEnvVarNames(config: ScopedQueryParams): string[];

package/build/workspace/queryParamResolution.js

@@ -0,0 +1,201 @@
+/**
+ * Path-scoped resolution for workspace-declared query params (SKYR-4127).
+ *
+ * SKYR-4050 shipped a single flat `api.defaultQueryParams` map applied
+ * identically to every generated request. That is too coarse for APIs whose
+ * authorization context is per-endpoint (e.g. an RBAC role validated against a
+ * different allow-list per path). `api.queryParamOverrides` layers path-scoped
+ * values on top of that base map.
+ *
+ * Deliberately free of filesystem access so it unit-tests directly — reading
+ * workspace.yml lives in utils/workspaceAuth.ts.
+ */
+import picomatch from "picomatch";
+import { logger } from "../utils/logger.js";
+import { pathFromEndpointURL } from "../utils/urlPath.js";
+/** Characters that terminate a pattern's literal prefix.
+ *
+ *  `{` counts because an OpenAPI-style `{id}` placeholder becomes `*` before
+ *  matching. `[` and `(` count because picomatch also treats character classes
+ *  (`[0-9]`) and extglobs (`+(a|b)`) as wildcards — without them a pattern like
+ *  `/v1/users/[0-9]*` would be ranked as though `[` were literal, scoring it
+ *  more specific than it is and letting it beat a genuinely narrower pattern. */
+const WILDCARD_CHARS = ["*", "?", "{", "[", "("];
+/** Pathname of a full endpoint URL, or undefined if unparseable.
+ *  `endpointURL` is contractually base URL + path, so the result includes any
+ *  base-path prefix: `https://host/api/v1/persons/42` -> `/api/v1/persons/42`.
+ *
+ *  Delegates to the shared helper so this module and the plan guard cannot
+ *  disagree about what an endpointURL's path is — the shared version also
+ *  restores `{param}` placeholders that `new URL()` percent-encodes, which
+ *  patterns are authored with. */
+export function extractPathname(endpointURL) {
+    return pathFromEndpointURL(endpointURL);
+}
+/** True when a resolved config would contribute no query params at all.
+ *  Both call sites skip the merge entirely in that case, so an empty
+ *  declaration leaves queryParams untouched rather than setting it to an empty
+ *  value. Defined once so the two sites cannot drift on what "empty" means. */
+export function contributesNothing(config) {
+    return Object.keys(config.base).length === 0 && config.overrides.length === 0;
+}
+/** Batch-scenario steps carry a bare path that may or may not be rooted. */
+export function ensureLeadingSlash(p) {
+    return p.startsWith("/") ? p : `/${p}`;
+}
+/** Rank for most-specific-wins: length of the literal prefix before the first
+ *  wildcard, computed on the ORIGINAL pattern so `{id}` still counts. */
+export function patternSpecificity(pathPattern) {
+    let earliest = pathPattern.length;
+    for (const ch of WILDCARD_CHARS) {
+        const idx = pathPattern.indexOf(ch);
+        if (idx !== -1 && idx < earliest)
+            earliest = idx;
+    }
+    return earliest;
+}
+/** Rewrite OpenAPI-style `{param}` placeholders to a single-segment wildcard.
+ *  Without this, picomatch reads `{id}` as brace alternation and matches only
+ *  the literal string `/v1/persons/id`. Brace alternation is therefore not
+ *  supported in patterns — an accepted trade. */
+function toGlob(pathPattern) {
+    return pathPattern.replace(/\{[^/}]*\}/g, "*");
+}
+function isStringMap(v) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return false;
+    return Object.values(v).every((x) => typeof x === "string");
+}
+/**
+ * Validate and coerce the raw `api.queryParamOverrides` value read from YAML.
+ *
+ * The read path in workspaceAuth.ts parses workspace.yml directly rather than
+ * through the Zod schema (the walk-up read must stay cheap), so nothing has
+ * validated this yet. Malformed entries are dropped with a warning instead of
+ * failing generation. Called once per load, not per request.
+ */
+export function normalizeOverrides(raw) {
+    if (!Array.isArray(raw)) {
+        if (raw !== undefined) {
+            logger.warning("Ignoring api.queryParamOverrides — expected a list", { got: typeof raw });
+        }
+        return [];
+    }
+    const result = [];
+    for (const entry of raw) {
+        const e = entry;
+        if (!e || typeof e !== "object" || typeof e.pathPattern !== "string" || e.pathPattern.length === 0) {
+            logger.warning("Skipping api.queryParamOverrides entry with a missing or empty pathPattern");
+            continue;
+        }
+        if (!isStringMap(e.values)) {
+            logger.warning("Skipping api.queryParamOverrides entry whose values are not a string map", {
+                pathPattern: e.pathPattern,
+            });
+            continue;
+        }
+        result.push({ pathPattern: e.pathPattern, values: e.values });
+    }
+    return result;
+}
+/**
+ * Validate and coerce the raw `api.defaultQueryParams` value read from YAML.
+ *
+ * Same reason `normalizeOverrides` exists: this read path deliberately bypasses
+ * the Zod schema, so nothing has checked the shape. Without this, a scalar
+ * declaration (`defaultQueryParams: just-a-string`) is spread by key and yields
+ * one query param per character — `0=j&1=u&2=s&…` sent to the server. A list
+ * behaves the same way, and a map with non-string values would reach
+ * mergeQueryParams* and be dropped there with a less specific warning.
+ *
+ * Anything that is not a plain object of string values degrades to an empty
+ * base map with a warning naming what was found.
+ */
+export function normalizeBaseMap(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (isStringMap(raw))
+        return raw;
+    logger.warning("Ignoring api.defaultQueryParams — expected a map of string values", { got: Array.isArray(raw) ? "array" : typeof raw });
+    return {};
+}
+/**
+ * Effective query params for one request path: the base map with the single
+ * most-specific matching override layered on top.
+ *
+ * Overrides never merge with each other — at most one wins. Ranking is by
+ * literal prefix length, then total pattern length, then document order.
+ *
+ * Whenever the patterns differ in specificity the result is independent of how
+ * the YAML list is ordered. Document order is only reached when two patterns
+ * tie on BOTH earlier criteria, and reordering the list does change the winner
+ * in that case — which is why a tie emits an ambiguity warning naming both
+ * patterns rather than resolving silently.
+ */
+export function resolveQueryParamsForPath(config, pathname) {
+    const matches = config.overrides
+        .map((override, index) => ({ override, index }))
+        .filter(({ override }) => picomatch.isMatch(pathname, toGlob(override.pathPattern)));
+    if (matches.length === 0)
+        return { ...config.base };
+    matches.sort((a, b) => {
+        const specDiff = patternSpecificity(b.override.pathPattern) - patternSpecificity(a.override.pathPattern);
+        if (specDiff !== 0)
+            return specDiff;
+        // Known limitation (Finding 5, SKYR-4127 final review): at equal literal-
+        // prefix length, this tiebreak prefers the LONGER total pattern — which
+        // is not always the narrower one. E.g. "/v1/persons/**" (14 chars) beats
+        // "/v1/persons/*" (13 chars) even though "**" matches strictly more paths
+        // than "*". Length is a proxy for specificity, not a guarantee of it; not
+        // fixed here since it would change ranking behavior for existing configs.
+        const lenDiff = b.override.pathPattern.length - a.override.pathPattern.length;
+        if (lenDiff !== 0)
+            return lenDiff;
+        return a.index - b.index;
+    });
+    const [winner, runnerUp] = matches;
+    if (runnerUp &&
+        patternSpecificity(winner.override.pathPattern) === patternSpecificity(runnerUp.override.pathPattern) &&
+        winner.override.pathPattern.length === runnerUp.override.pathPattern.length) {
+        logger.warning("Ambiguous api.queryParamOverrides — two equally specific patterns match this path; using the first", {
+            pathname,
+            patterns: [winner.override.pathPattern, runnerUp.override.pathPattern],
+        });
+    }
+    return { ...config.base, ...winner.override.values };
+}
+/** `env.VAR` / legacy `envs.VAR`, anchored so a literal that merely contains
+ *  the prefix (`prod.env.HOST`) is not mistaken for a reference, and requiring
+ *  at least one character of variable name. Case-sensitive, matching the
+ *  schema's documented behavior: `ENV.VAR` is an ordinary literal. */
+const ENV_REFERENCE = /^envs?\.(.+)$/;
+/** Environment variables this workspace's query params defer to, in declaration
+ *  order and deduplicated (SKYR-4127).
+ *
+ *  These references resolve where the test RUNS, so under Testbot they resolve
+ *  inside the executor container — whose environment is a fixed allowlist. A
+ *  name that never reaches the container resolves to nothing, and an unresolved
+ *  query param is dropped from the request silently, producing a passing test
+ *  that exercised the wrong identity. The executor uses this list to forward
+ *  exactly what the workspace asked for.
+ *
+ *  Deliberately derived from the declarations rather than from the ambient
+ *  environment: nothing is forwarded that workspace.yml did not name.
+ *
+ *  Both maps are read even though `defaultQueryParams` documents itself as
+ *  literal-only — that is a doc contract the core loader does not enforce, and
+ *  a declaration there would otherwise reproduce the original silent failure. */
+export function extractEnvVarNames(config) {
+    const names = new Set();
+    const collect = (values) => {
+        for (const value of Object.values(values)) {
+            const match = typeof value === "string" ? ENV_REFERENCE.exec(value) : null;
+            if (match)
+                names.add(match[1]);
+        }
+    };
+    collect(config.base);
+    for (const override of config.overrides)
+        collect(override.values);
+    return [...names];
+}

package/build/workspace/workspace.d.ts

@@ -19,6 +19,34 @@ export declare const serviceSchema: z.ZodObject<{
          *  Explicit per-request queryParams always win on a key collision
          *  (SKYR-4050). */
         defaultQueryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** Path-scoped overrides layered on top of defaultQueryParams
+         *  (SKYR-4127). For a given request, the single most-specific matching
+         *  pathPattern wins and its values override the base map key by key;
+         *  overrides never merge with each other. Patterns are picomatch globs
+         *  matched against the request URL pathname, with OpenAPI-style
+         *  `{param}` placeholders treated as a single-segment wildcard.
+         *
+         *  The pathname includes any base-path prefix carried by baseUrl — a
+         *  service at `https://host/api` needs `/api/v1/**`, not `/v1/**`. A
+         *  pattern that omits the prefix silently matches nothing.
+         *
+         *  Values may use `env.VAR` to defer to an environment variable read
+         *  where the test runs rather than where it was generated — the
+         *  generated test carries the lookup itself (os.getenv in Python,
+         *  process.env in JS/TS, System.getenv in Java). The legacy `envs.`
+         *  spelling is still accepted. Note the variable name is passed
+         *  through verbatim and is case-sensitive; a near miss such as
+         *  `ENV.VAR` is treated as an ordinary literal. */
+        queryParamOverrides: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            pathPattern: z.ZodString;
+            values: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            values: Record<string, string>;
+            pathPattern: string;
+        }, {
+            values: Record<string, string>;
+            pathPattern: string;
+        }>, "many">>;
         baseUrl: z.ZodOptional<z.ZodString>;
         /** SUT serves self-signed TLS (e.g. a kind kube-apiserver) — generated
          *  tests should skip certificate verification for this service (SKYR-3961).
@@ -30,6 +58,10 @@ export declare const serviceSchema: z.ZodObject<{
         schemaPath?: string | undefined;
         authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
         defaultQueryParams?: Record<string, string> | undefined;
+        queryParamOverrides?: {
+            values: Record<string, string>;
+            pathPattern: string;
+        }[] | undefined;
         baseUrl?: string | undefined;
         skipTLSVerify?: boolean | undefined;
     }, {
@@ -38,6 +70,10 @@ export declare const serviceSchema: z.ZodObject<{
         schemaPath?: string | undefined;
         authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
         defaultQueryParams?: Record<string, string> | undefined;
+        queryParamOverrides?: {
+            values: Record<string, string>;
+            pathPattern: string;
+        }[] | undefined;
         baseUrl?: string | undefined;
         skipTLSVerify?: boolean | undefined;
     }>>;
@@ -114,6 +150,10 @@ export declare const serviceSchema: z.ZodObject<{
         schemaPath?: string | undefined;
         authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
         defaultQueryParams?: Record<string, string> | undefined;
+        queryParamOverrides?: {
+            values: Record<string, string>;
+            pathPattern: string;
+        }[] | undefined;
         baseUrl?: string | undefined;
         skipTLSVerify?: boolean | undefined;
     } | undefined;
@@ -145,6 +185,10 @@ export declare const serviceSchema: z.ZodObject<{
         schemaPath?: string | undefined;
         authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
         defaultQueryParams?: Record<string, string> | undefined;
+        queryParamOverrides?: {
+            values: Record<string, string>;
+            pathPattern: string;
+        }[] | undefined;
         baseUrl?: string | undefined;
         skipTLSVerify?: boolean | undefined;
     } | undefined;
@@ -212,6 +256,34 @@ export declare const workspaceConfigSchema: z.ZodObject<{
              *  Explicit per-request queryParams always win on a key collision
              *  (SKYR-4050). */
             defaultQueryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            /** Path-scoped overrides layered on top of defaultQueryParams
+             *  (SKYR-4127). For a given request, the single most-specific matching
+             *  pathPattern wins and its values override the base map key by key;
+             *  overrides never merge with each other. Patterns are picomatch globs
+             *  matched against the request URL pathname, with OpenAPI-style
+             *  `{param}` placeholders treated as a single-segment wildcard.
+             *
+             *  The pathname includes any base-path prefix carried by baseUrl — a
+             *  service at `https://host/api` needs `/api/v1/**`, not `/v1/**`. A
+             *  pattern that omits the prefix silently matches nothing.
+             *
+             *  Values may use `env.VAR` to defer to an environment variable read
+             *  where the test runs rather than where it was generated — the
+             *  generated test carries the lookup itself (os.getenv in Python,
+             *  process.env in JS/TS, System.getenv in Java). The legacy `envs.`
+             *  spelling is still accepted. Note the variable name is passed
+             *  through verbatim and is case-sensitive; a near miss such as
+             *  `ENV.VAR` is treated as an ordinary literal. */
+            queryParamOverrides: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                pathPattern: z.ZodString;
+                values: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                values: Record<string, string>;
+                pathPattern: string;
+            }, {
+                values: Record<string, string>;
+                pathPattern: string;
+            }>, "many">>;
             baseUrl: z.ZodOptional<z.ZodString>;
             /** SUT serves self-signed TLS (e.g. a kind kube-apiserver) — generated
              *  tests should skip certificate verification for this service (SKYR-3961).
@@ -223,6 +295,10 @@ export declare const workspaceConfigSchema: z.ZodObject<{
             schemaPath?: string | undefined;
             authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
+            queryParamOverrides?: {
+                values: Record<string, string>;
+                pathPattern: string;
+            }[] | undefined;
             baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         }, {
@@ -231,6 +307,10 @@ export declare const workspaceConfigSchema: z.ZodObject<{
             schemaPath?: string | undefined;
             authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
+            queryParamOverrides?: {
+                values: Record<string, string>;
+                pathPattern: string;
+            }[] | undefined;
             baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         }>>;
@@ -307,6 +387,10 @@ export declare const workspaceConfigSchema: z.ZodObject<{
             schemaPath?: string | undefined;
             authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
+            queryParamOverrides?: {
+                values: Record<string, string>;
+                pathPattern: string;
+            }[] | undefined;
             baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
@@ -338,6 +422,10 @@ export declare const workspaceConfigSchema: z.ZodObject<{
             schemaPath?: string | undefined;
             authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
+            queryParamOverrides?: {
+                values: Record<string, string>;
+                pathPattern: string;
+            }[] | undefined;
             baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
@@ -382,6 +470,10 @@ export declare const workspaceConfigSchema: z.ZodObject<{
             schemaPath?: string | undefined;
             authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
+            queryParamOverrides?: {
+                values: Record<string, string>;
+                pathPattern: string;
+            }[] | undefined;
             baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
@@ -426,6 +518,10 @@ export declare const workspaceConfigSchema: z.ZodObject<{
             schemaPath?: string | undefined;
             authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
+            queryParamOverrides?: {
+                values: Record<string, string>;
+                pathPattern: string;
+            }[] | undefined;
             baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
@@ -479,6 +575,10 @@ export declare function validateWorkspaceConfig(config: unknown): z.SafeParseRet
             schemaPath?: string | undefined;
             authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
+            queryParamOverrides?: {
+                values: Record<string, string>;
+                pathPattern: string;
+            }[] | undefined;
             baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;
@@ -523,6 +623,10 @@ export declare function validateWorkspaceConfig(config: unknown): z.SafeParseRet
             schemaPath?: string | undefined;
             authType?: "none" | "token" | "bearer" | "basic" | "oauth" | "apiKey" | "cookie" | "session" | undefined;
             defaultQueryParams?: Record<string, string> | undefined;
+            queryParamOverrides?: {
+                values: Record<string, string>;
+                pathPattern: string;
+            }[] | undefined;
             baseUrl?: string | undefined;
             skipTLSVerify?: boolean | undefined;
         } | undefined;

package/build/workspace/workspace.js

@@ -61,6 +61,30 @@ export const serviceSchema = z
          *  Explicit per-request queryParams always win on a key collision
          *  (SKYR-4050). */
         defaultQueryParams: z.record(z.string()).optional(),
+        /** Path-scoped overrides layered on top of defaultQueryParams
+         *  (SKYR-4127). For a given request, the single most-specific matching
+         *  pathPattern wins and its values override the base map key by key;
+         *  overrides never merge with each other. Patterns are picomatch globs
+         *  matched against the request URL pathname, with OpenAPI-style
+         *  `{param}` placeholders treated as a single-segment wildcard.
+         *
+         *  The pathname includes any base-path prefix carried by baseUrl — a
+         *  service at `https://host/api` needs `/api/v1/**`, not `/v1/**`. A
+         *  pattern that omits the prefix silently matches nothing.
+         *
+         *  Values may use `env.VAR` to defer to an environment variable read
+         *  where the test runs rather than where it was generated — the
+         *  generated test carries the lookup itself (os.getenv in Python,
+         *  process.env in JS/TS, System.getenv in Java). The legacy `envs.`
+         *  spelling is still accepted. Note the variable name is passed
+         *  through verbatim and is case-sensitive; a near miss such as
+         *  `ENV.VAR` is treated as an ordinary literal. */
+        queryParamOverrides: z
+            .array(z.object({
+            pathPattern: z.string().min(1),
+            values: z.record(z.string()),
+        }).strict())
+            .optional(),
         baseUrl: z.string().optional(),
         /** SUT serves self-signed TLS (e.g. a kind kube-apiserver) — generated
          *  tests should skip certificate verification for this service (SKYR-3961).