@to11ai/sdk 0.1.1 → 0.2.0

package/src/behaviors/store.ts

@@ -0,0 +1,175 @@
+/**
+ * Published-SDK behavior resolution (TO11-2100 / feature-flagging Slice S7).
+ *
+ * The to11 platform evaluates flags that influence *shipped-SDK behavior*
+ * server-side and delivers their values on the optional `sdkBehavior` field of
+ * the success envelope (PRD Decision 7). This SDK carries **no** LaunchDarkly
+ * dependency and never connects to to11's control plane — it only reads the
+ * value the server already evaluated.
+ *
+ * Resolution precedence, applied by {@link BehaviorStore.resolve}:
+ *   1. local override  — init option, then env var (init option wins ties)
+ *   2. server-delivered value — the last value stored for that key
+ *   3. coded default   — the value the caller passes to `resolve`
+ *
+ * A value whose runtime type disagrees with the coded default's type falls
+ * through to the next tier (ultimately the coded default), mirroring the
+ * server wrapper's kind-guard. An absent envelope field never clears
+ * previously-stored values.
+ */
+
+/** The wire shape of the optional `sdkBehavior` envelope field. */
+export interface SdkBehaviorEnvelope {
+	readonly v: number;
+	readonly flags: Record<string, unknown>;
+}
+
+/**
+ * The only `sdkBehavior.v` this SDK understands. A response carrying any other
+ * version is ignored wholesale (the store is left untouched), so a future
+ * envelope shape can never break this SDK — it degrades to coded defaults, the
+ * safe state.
+ */
+const SUPPORTED_SDK_BEHAVIOR_VERSION = 1;
+
+/** Env-var prefix for local SDK-behavior overrides: `TO11_SDK_BEHAVIOR_<KEY>`. */
+const ENV_PREFIX = "TO11_SDK_BEHAVIOR_";
+
+/**
+ * Convert a namespaced flag key to its env-var name: prefix + uppercased key
+ * with `.` and `-` replaced by `_`. e.g. `sdk.retry-v2` →
+ * `TO11_SDK_BEHAVIOR_SDK_RETRY_V2`.
+ */
+export const envVarNameForKey = (key: string): string =>
+	`${ENV_PREFIX}${key.toUpperCase().replace(/[.-]/g, "_")}`;
+
+/** Parse a JSON value out of an env-var string, falling back to the raw string. */
+const parseEnvValue = (raw: string): unknown => {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+};
+
+/**
+ * Reject a candidate value whose runtime type disagrees with the coded
+ * default's type, for primitive defaults. Objects/arrays (JSON defaults) accept
+ * any non-null object candidate. `null`/`undefined` candidates are always
+ * rejected (treated as absent).
+ */
+const typeMatchesDefault = <T>(
+	candidate: unknown,
+	codedDefault: T,
+): boolean => {
+	if (candidate === null || candidate === undefined) {
+		return false;
+	}
+	const defaultType = typeof codedDefault;
+	if (
+		defaultType === "boolean" ||
+		defaultType === "string" ||
+		defaultType === "number"
+	) {
+		return typeof candidate === defaultType;
+	}
+	// JSON default: preserve container kind (array vs object) so an array
+	// default does not accept a plain object and vice versa. This matches the
+	// python-sdk store (which distinguishes mapping vs list/tuple) so identical
+	// payloads resolve identically across SDKs.
+	if (defaultType === "object" && codedDefault !== null) {
+		if (Array.isArray(codedDefault)) {
+			return Array.isArray(candidate);
+		}
+		return typeof candidate === "object" && !Array.isArray(candidate);
+	}
+	// Unusual default types — accept on exact typeof match.
+	return typeof candidate === defaultType;
+};
+
+export interface BehaviorStoreOptions {
+	/** Init-time local overrides, keyed by namespaced flag key. Highest precedence. */
+	readonly initOverrides?: Record<string, unknown>;
+	/**
+	 * The process environment to read `TO11_SDK_BEHAVIOR_*` overrides from.
+	 * Pass `undefined` (the default) in browser contexts so the SDK never
+	 * touches `process.env`.
+	 */
+	readonly env?: Record<string, string | undefined>;
+}
+
+export class BehaviorStore {
+	/** Last-write-wins server-delivered values, keyed by namespaced flag key. */
+	private readonly serverValues = new Map<string, unknown>();
+	/** Init-option overrides, keyed by flag key. */
+	private readonly initOverrides: ReadonlyMap<string, unknown>;
+	/** Env-var overrides, keyed by full env-var name (e.g. `TO11_SDK_BEHAVIOR_SDK_RETRY_V2`). */
+	private readonly envOverrides: ReadonlyMap<string, unknown>;
+
+	constructor(options?: BehaviorStoreOptions) {
+		this.initOverrides = new Map(Object.entries(options?.initOverrides ?? {}));
+
+		const env = options?.env;
+		const envMap = new Map<string, unknown>();
+		if (env) {
+			for (const [name, raw] of Object.entries(env)) {
+				if (raw !== undefined && name.startsWith(ENV_PREFIX)) {
+					envMap.set(name, parseEnvValue(raw));
+				}
+			}
+		}
+		this.envOverrides = envMap;
+	}
+
+	/**
+	 * Update the server-delivered values from a response's `sdkBehavior` field.
+	 * No-op when the field is absent or carries an unsupported version. Never
+	 * clears previously-stored values.
+	 */
+	updateFromEnvelope(sdkBehavior: SdkBehaviorEnvelope | undefined): void {
+		if (
+			sdkBehavior === undefined ||
+			sdkBehavior.v !== SUPPORTED_SDK_BEHAVIOR_VERSION ||
+			typeof sdkBehavior.flags !== "object" ||
+			sdkBehavior.flags === null
+		) {
+			return;
+		}
+		for (const [key, value] of Object.entries(sdkBehavior.flags)) {
+			this.serverValues.set(key, value);
+		}
+	}
+
+	/**
+	 * Resolve a behavior value under the fixed precedence: local override (init
+	 * option, then env var) → server-delivered value → coded default. A tier
+	 * whose value is absent or type-mismatched against `codedDefault` falls
+	 * through to the next tier.
+	 */
+	resolve<T>(key: string, codedDefault: T): T {
+		// 1a. Init-option override (highest precedence).
+		if (this.initOverrides.has(key)) {
+			const value = this.initOverrides.get(key);
+			if (typeMatchesDefault(value, codedDefault)) {
+				return value as T;
+			}
+		}
+		// 1b. Env-var override.
+		const envName = envVarNameForKey(key);
+		if (this.envOverrides.has(envName)) {
+			const value = this.envOverrides.get(envName);
+			if (typeMatchesDefault(value, codedDefault)) {
+				return value as T;
+			}
+		}
+		// 2. Server-delivered value.
+		if (this.serverValues.has(key)) {
+			const value = this.serverValues.get(key);
+			if (typeMatchesDefault(value, codedDefault)) {
+				return value as T;
+			}
+		}
+		// 3. Coded default.
+		return codedDefault;
+	}
+}

package/src/client.ts

@@ -1,15 +1,37 @@
+import { BehaviorStore } from "./behaviors/store";
 import { ProjectEnvironmentResource } from "./projectEnvironments/resource";
 import type { CacheConfig } from "./prompts/cache";
 import { PromptResource } from "./prompts/resource";
+import { ENV_SLUG_REGEX } from "./prompts/types";
 import { RoutingRulesResource } from "./routingRules/resource";
 import { Transport } from "./transport";
 
+// SDK-behavior delivery (TO11-2100): the resolution store + helpers.
+export {
+	BehaviorStore,
+	type BehaviorStoreOptions,
+	envVarNameForKey,
+	type SdkBehaviorEnvelope,
+} from "./behaviors/store";
 // Re-export all error types for convenience
-export type { NoApplicableRouteReason } from "./errors";
+export type {
+	AmbiguousEnvLabelsReason,
+	EnvNotFoundReason,
+	NoActiveReleaseReason,
+	NoApplicableRouteReason,
+	PromptNotFoundReason,
+	PromptPolicyViolationReason,
+} from "./errors";
 export {
+	// TO11-980 (S9) prompt-resolution typed errors.
+	AmbiguousEnvLabelsError,
 	EnvNotEnabledForProviderError,
+	EnvNotFoundError,
+	NoActiveReleaseError,
 	NoApplicableRouteError,
 	PromptLabelNotRegisteredError,
+	PromptNotFoundError,
+	PromptPolicyViolationError,
 	RuleNotFoundError,
 	RuleVersionInvalidSnapshotError,
 	To11aiApiError,
@@ -39,7 +61,20 @@ export type {
 } from "./projectEnvironments/resource";
 export { ProjectEnvironmentResource } from "./projectEnvironments/resource";
 export type { CacheConfig } from "./prompts/cache";
+export type { PromptResourceConfig } from "./prompts/resource";
 export { PromptResource } from "./prompts/resource";
+// TO11-980 (S9): env-aware fetch() surface types at the package entrypoint (AC9).
+export type {
+	BlockRenderRecord,
+	FetchedPrompt,
+	FetchPromptOptions,
+	PromptContext,
+	RenderedChatMessage,
+	RenderedPrompt,
+	ResolvedPrompt,
+	ResolvedPromptEnvelope,
+} from "./prompts/types";
+export { ENV_SLUG_REGEX } from "./prompts/types";
 export type {
 	CreateRuleVersionInput,
 	CreateRuleVersionResult,
@@ -92,12 +127,37 @@ type AuthOptions = ServerAuthOptions | BrowserAuthOptions;
 
 export type ClientOptions = AuthOptions & {
 	baseUrl: string;
+	/**
+	 * Project the client is bound to (TO11-980 / S9). Required for the
+	 * env-aware `prompts.fetch(slug, …)` surface, which builds the
+	 * project-scoped resolve path from it. Validated non-empty at
+	 * construction. The deprecated `prompts.resolve()` keeps its per-call
+	 * `projectId` and ignores this.
+	 */
+	projectId?: string;
+	/**
+	 * Default serving environment for `prompts.fetch(slug)` (TO11-980 / S9,
+	 * Style-A). When set, every `fetch()` call inherits it unless overridden
+	 * per call. Validated eagerly against the project-environments registry
+	 * rule (lowercase-kebab, `^[a-z0-9-]{1,63}$`): empty / whitespace-only /
+	 * uppercase / 64+-char values throw at construction with a loud
+	 * `[to11ai/sdk]` message before any request hits the wire.
+	 */
+	env?: string;
 	/** LRU cache configuration for resolve(). Defaults: ttlSeconds=300, maxEntries=100 */
 	cache?: CacheConfig;
 	/** Request timeout in milliseconds. Default: 30_000 */
 	timeoutMs?: number;
 	/** Max retry attempts for network errors / 5xx. Default: 3 */
 	maxRetries?: number;
+	/**
+	 * Purely local overrides for server-evaluated SDK-behavior flags (TO11-2100),
+	 * keyed by namespaced flag key (e.g. `{ "sdk.retry-v2": true }`). These take
+	 * precedence over server-delivered values and the SDK's coded defaults. For
+	 * the same flag key, an init option here wins over a `TO11_SDK_BEHAVIOR_*`
+	 * environment variable. Published-SDK only — no LaunchDarkly involved.
+	 */
+	behaviorOverrides?: Record<string, unknown>;
 };
 
 // ─── Client interface ──────────────────────────────────────────────────────
@@ -106,6 +166,16 @@ export interface To11aiClient {
 	readonly prompts: PromptResource;
 	readonly projectEnvironments: ProjectEnvironmentResource;
 	readonly routingRules: RoutingRulesResource;
+	/**
+	 * Resolve a server-evaluated SDK-behavior flag value (TO11-2100) under the
+	 * fixed precedence: local override (init option → `TO11_SDK_BEHAVIOR_*` env
+	 * var) → server-delivered value (captured from responses the client has
+	 * already made) → the `codedDefault` passed here. A value whose runtime type
+	 * disagrees with `codedDefault` falls through to the next tier. The SDK
+	 * carries no LaunchDarkly dependency; this only reads what the server
+	 * delivered on the envelope.
+	 */
+	readonly resolveBehavior: <T>(key: string, codedDefault: T) => T;
 }
 
 // ─── Factory ───────────────────────────────────────────────────────────────
@@ -147,6 +217,23 @@ export function createClient(options: ClientOptions): To11aiClient {
 		throw new Error("[to11ai/sdk] `apiKey` must not be an empty string.");
 	}
 
+	// R0: validate `projectId` eagerly when supplied (loud throw). An empty /
+	// whitespace-only value is a misconfiguration; reject before any request.
+	if (options.projectId !== undefined && options.projectId.trim() === "") {
+		throw new Error(
+			"[to11ai/sdk] `projectId` must not be an empty string — omit it or pass a valid project id.",
+		);
+	}
+
+	// R1: validate the init-time `env` against the project-environments
+	// registry rule (stricter than gatewayAuthHeaders' empty-only check) so a
+	// malformed env fails locally rather than round-tripping to ENV_NOT_FOUND.
+	if (options.env !== undefined && !ENV_SLUG_REGEX.test(options.env)) {
+		throw new Error(
+			`[to11ai/sdk] \`env\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(options.env)}`,
+		);
+	}
+
 	// TypeScript's union type prevents callers from providing both, but JS consumers can.
 	// Perform an explicit XOR check at runtime to catch the case where both are supplied.
 	const hasApiKey = options.apiKey !== undefined;
@@ -164,16 +251,41 @@ export function createClient(options: ClientOptions): To11aiClient {
 			? ({ apiKey: options.apiKey } as const)
 			: ({ getAccessToken: getAccessToken as () => Promise<string> } as const);
 
+	// SDK-behavior store (TO11-2100). Env-var overrides (`TO11_SDK_BEHAVIOR_*`)
+	// are read ONLY in a non-browser context so the published browser bundle
+	// never touches `process.env`; init-option overrides apply everywhere.
+	const isBrowser = isDomBrowser || isWorkerBrowser;
+	const processEnv =
+		!isBrowser &&
+		typeof process !== "undefined" &&
+		typeof process.env === "object"
+			? process.env
+			: undefined;
+	const behaviorStore = new BehaviorStore({
+		initOverrides: options.behaviorOverrides,
+		env: processEnv,
+	});
+
 	const transport = new Transport({
 		baseUrl: options.baseUrl,
 		auth,
 		timeoutMs: options.timeoutMs,
 		maxRetries: options.maxRetries,
+		behaviorStore,
 	});
 
-	const prompts = new PromptResource(transport, options.cache);
+	const prompts = new PromptResource(transport, options.cache, {
+		projectId: options.projectId,
+		env: options.env,
+	});
 	const projectEnvironments = new ProjectEnvironmentResource(transport);
 	const routingRules = new RoutingRulesResource(transport);
 
-	return { prompts, projectEnvironments, routingRules };
+	return {
+		prompts,
+		projectEnvironments,
+		routingRules,
+		resolveBehavior: (key, codedDefault) =>
+			behaviorStore.resolve(key, codedDefault),
+	};
 }

package/src/errors.ts

@@ -90,6 +90,29 @@ export class To11aiNetworkError extends To11aiError {
 	}
 }
 
+/**
+ * Thrown when a 2xx response body fails runtime validation against the
+ * generated wire schema. Distinct from `To11aiValidationError`, which models a
+ * server-side 4xx validation rejection.
+ */
+export class To11aiResponseValidationError extends To11aiError {
+	readonly path: string;
+	readonly issues: { message: string; path: (string | number)[] }[];
+
+	constructor(path: string, zodError: unknown, cause?: unknown) {
+		super(`[to11ai/sdk] Response from ${path} failed schema validation`, {
+			cause,
+		});
+		this.name = "To11aiResponseValidationError";
+		this.path = path;
+		const candidate = (zodError as { issues?: unknown })?.issues;
+		this.issues = Array.isArray(candidate)
+			? (candidate as { message: string; path: (string | number)[] }[])
+			: [];
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+}
+
 /**
  * Thrown when strict-mode rejects a label move for an unregistered label.
  *
@@ -227,6 +250,244 @@ export class EnvNotEnabledForProviderError extends To11aiApiError {
 	}
 }
 
+// ─── Prompt resolution typed errors (TO11-980 / S9) ────────────────────────
+//
+// These four subclasses give `prompts.fetch()` callers a discriminable error
+// family for prompt resolution. Each:
+//   - extends `To11aiApiError`, so existing broad `catch (err instanceof
+//     To11aiApiError)` blocks keep matching (AC8),
+//   - carries a structured `reason` payload (not a bare string),
+//   - ships a `static is()` type guard like its siblings.
+//
+// IMPORTANT — wire mapping (server TO11-1925/1926): the canonical
+// SCREAMING_SNAKE error code lives in the envelope's `error.details.code`
+// (e.g. `PROMPT_NOT_FOUND`), NOT top-level `error.code` (which carries the
+// generic HTTP class `not_found` / `conflict` / `unprocessable_entity`). The
+// transport mapper reads `details.code` for these four branches — see
+// `transport.ts`. `errorCode` on the constructed error is set to that
+// canonical `details.code` so call sites can switch on it consistently.
+
+/**
+ * Reason payload for `PromptNotFoundError`.
+ *
+ * Surfaced when the server cannot resolve the prompt for the given slug
+ * (`PROMPT_NOT_FOUND`) or cannot find a version matching the supplied
+ * labels (`PROMPT_LABELS_NOT_FOUND`). `slug` / `projectId` are echoed from
+ * the request context when the server provides them in `details`.
+ */
+export interface PromptNotFoundReason {
+	slug?: string;
+	projectId?: string;
+}
+
+/**
+ * Thrown when a prompt cannot be resolved. Covers two server codes (single
+ * class so one `catch` matches both):
+ *
+ *   * `PROMPT_NOT_FOUND` — no prompt exists for the requested slug.
+ *   * `PROMPT_LABELS_NOT_FOUND` — the prompt exists but no version matches
+ *     all the supplied labels (the `env`→label resolution found nothing).
+ *
+ * Surfaces at HTTP 404 (the canonical code lives in `details.code`).
+ */
+export class PromptNotFoundError extends To11aiApiError {
+	readonly reason: PromptNotFoundReason;
+
+	constructor(
+		message: string,
+		errorCode: string,
+		reason: PromptNotFoundReason,
+		details?: unknown,
+		statusCode = 404,
+	) {
+		super(message, statusCode, errorCode, details);
+		this.name = "PromptNotFoundError";
+		this.reason = reason;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	static is(err: unknown): err is PromptNotFoundError {
+		return err instanceof PromptNotFoundError;
+	}
+}
+
+/**
+ * Reason payload for `EnvNotFoundError`.
+ *
+ * `source` discriminates the two failure modes (D2):
+ *   - `"missing"` — no env was supplied at init OR at call time. Raised
+ *     CLIENT-side, eagerly, before any request (R4 / AC4); `env` is absent.
+ *   - `"unknown"` — an env was supplied but the server's registry has no
+ *     such (active) env. Surfaced from the `ENV_NOT_FOUND` server code; `env`
+ *     carries the rejected slug when the server echoes it.
+ */
+export interface EnvNotFoundReason {
+	env?: string;
+	source: "missing" | "unknown";
+}
+
+/**
+ * Thrown when no serving environment can be resolved for a `prompts.fetch()`
+ * call. One class, two `reason.source` discriminants (see
+ * `EnvNotFoundReason`): client-eager `"missing"` (R4) and server-forwarded
+ * `"unknown"` (`ENV_NOT_FOUND`).
+ *
+ * The client-eager variant carries no `statusCode`/`errorCode` from the wire
+ * (no request was made); it reports status `0` and errorCode `ENV_NOT_FOUND`
+ * for a uniform catch surface.
+ */
+export class EnvNotFoundError extends To11aiApiError {
+	readonly reason: EnvNotFoundReason;
+
+	constructor(
+		message: string,
+		reason: EnvNotFoundReason,
+		details: unknown,
+		// Required (no misleading default): the client-eager `missing()` variant
+		// passes 0 (no HTTP call) and the transport mapper passes the real server
+		// status, so a hardcoded default would never reflect reality.
+		statusCode: number,
+	) {
+		super(message, statusCode, "ENV_NOT_FOUND", details);
+		this.name = "EnvNotFoundError";
+		this.reason = reason;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	/** Build the client-eager (missing-at-both) variant — no transport call. */
+	static missing(env?: string): EnvNotFoundError {
+		return new EnvNotFoundError(
+			"[to11ai/sdk] No environment resolvable for prompts.fetch(): none supplied at client init and none supplied per call. Pass `env` to createClient or fetch(slug, { env }).",
+			{ env, source: "missing" },
+			undefined,
+			0,
+		);
+	}
+
+	static is(err: unknown): err is EnvNotFoundError {
+		return err instanceof EnvNotFoundError;
+	}
+}
+
+/**
+ * Reason payload for `NoActiveReleaseError`.
+ *
+ * Identifies the prompt (by `slug` and/or `promptId`) and the `env` for
+ * which no active release row exists.
+ */
+export interface NoActiveReleaseReason {
+	slug?: string;
+	promptId?: string;
+	env?: string;
+}
+
+/**
+ * Thrown when a prompt resolves but has no active release for the requested
+ * env (`NO_ACTIVE_RELEASE`). The release primitive (S3) found the prompt but
+ * nothing is currently serving in that environment.
+ */
+export class NoActiveReleaseError extends To11aiApiError {
+	readonly reason: NoActiveReleaseReason;
+
+	constructor(
+		message: string,
+		reason: NoActiveReleaseReason,
+		details?: unknown,
+		statusCode = 409,
+	) {
+		super(message, statusCode, "NO_ACTIVE_RELEASE", details);
+		this.name = "NoActiveReleaseError";
+		this.reason = reason;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	static is(err: unknown): err is NoActiveReleaseError {
+		return err instanceof NoActiveReleaseError;
+	}
+}
+
+/**
+ * Reason payload for `PromptPolicyViolationError`.
+ *
+ * `code` is the specific server policy code (`POLICY_VIOLATION` or one of the
+ * `ENV_POLICY_*` family from S5 / TO11-976). `policy` / `detail` are
+ * server-shaped and forwarded verbatim when present.
+ */
+export interface PromptPolicyViolationReason {
+	code: string;
+	policy?: string;
+	detail?: unknown;
+}
+
+/**
+ * Thrown when the server's S5 environment-policy machinery rejects a
+ * resolution. Forwarded verbatim from the server policy codes — the generic
+ * `POLICY_VIOLATION` and the `ENV_POLICY_*` family (required-source-env,
+ * minimum-dwell-time, requires-approval, separation-of-duties, …).
+ *
+ * CRITICAL (D3 branch-ordering): the server can return a policy violation at
+ * HTTP 403. The transport mapper MUST match this (by `details.code`) BEFORE
+ * the generic `401 || 403 → To11aiAuthError` guard, otherwise a 403 policy
+ * error would be swallowed as an auth error (AC6).
+ */
+export class PromptPolicyViolationError extends To11aiApiError {
+	readonly reason: PromptPolicyViolationReason;
+
+	constructor(
+		message: string,
+		reason: PromptPolicyViolationReason,
+		details?: unknown,
+		statusCode = 403,
+	) {
+		super(message, statusCode, reason.code, details);
+		this.name = "PromptPolicyViolationError";
+		this.reason = reason;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	static is(err: unknown): err is PromptPolicyViolationError {
+		return err instanceof PromptPolicyViolationError;
+	}
+}
+
+/**
+ * Reason payload for `AmbiguousEnvLabelsError`.
+ *
+ * Carried when the supplied env-label matched more than one candidate
+ * version and the server cannot pick deterministically
+ * (`AMBIGUOUS_ENV_LABELS`).
+ */
+export interface AmbiguousEnvLabelsReason {
+	env?: string;
+	slug?: string;
+}
+
+/**
+ * Thrown when the env→label resolution is ambiguous on the server
+ * (`AMBIGUOUS_ENV_LABELS`) — the label matched multiple candidates and the
+ * server declines to guess. Surfaces (rather than 500ing) so callers get a
+ * typed, actionable error.
+ */
+export class AmbiguousEnvLabelsError extends To11aiApiError {
+	readonly reason: AmbiguousEnvLabelsReason;
+
+	constructor(
+		message: string,
+		reason: AmbiguousEnvLabelsReason,
+		details?: unknown,
+		statusCode = 409,
+	) {
+		super(message, statusCode, "AMBIGUOUS_ENV_LABELS", details);
+		this.name = "AmbiguousEnvLabelsError";
+		this.reason = reason;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	static is(err: unknown): err is AmbiguousEnvLabelsError {
+		return err instanceof AmbiguousEnvLabelsError;
+	}
+}
+
 /**
  * Thrown when version create rejects the snapshot for a structural
  * reason — invalid variant params, malformed `when` clause, illegal