@to11ai/sdk 0.1.2 → 0.2.0

package/dist/behaviors/store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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>;
+}
+/**
+ * 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 declare const envVarNameForKey: (key: string) => string;
+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 declare class BehaviorStore {
+    /** Last-write-wins server-delivered values, keyed by namespaced flag key. */
+    private readonly serverValues;
+    /** Init-option overrides, keyed by flag key. */
+    private readonly initOverrides;
+    /** Env-var overrides, keyed by full env-var name (e.g. `TO11_SDK_BEHAVIOR_SDK_RETRY_V2`). */
+    private readonly envOverrides;
+    constructor(options?: BehaviorStoreOptions);
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/dist/client.cjs

@@ -41,6 +41,7 @@ var exports_client = {};
 __export(exports_client, {
   gatewayPromptHeaders: () => import_gateway.gatewayPromptHeaders,
   gatewayAuthHeaders: () => import_gateway.gatewayAuthHeaders,
+  envVarNameForKey: () => import_store2.envVarNameForKey,
   createClient: () => createClient,
   To11aiValidationError: () => import_errors.To11aiValidationError,
   To11aiRateLimitError: () => import_errors.To11aiRateLimitError,
@@ -54,20 +55,31 @@ __export(exports_client, {
   RoutingRuleVersionResource: () => import_resource6.RoutingRuleVersionResource,
   RoutingRuleReleaseResource: () => import_resource6.RoutingRuleReleaseResource,
   PromptResource: () => import_resource5.PromptResource,
+  PromptPolicyViolationError: () => import_errors.PromptPolicyViolationError,
+  PromptNotFoundError: () => import_errors.PromptNotFoundError,
   PromptLabelNotRegisteredError: () => import_errors.PromptLabelNotRegisteredError,
   ProjectEnvironmentResource: () => import_resource4.ProjectEnvironmentResource,
   NoApplicableRouteError: () => import_errors.NoApplicableRouteError,
-  EnvNotEnabledForProviderError: () => import_errors.EnvNotEnabledForProviderError
+  NoActiveReleaseError: () => import_errors.NoActiveReleaseError,
+  EnvNotFoundError: () => import_errors.EnvNotFoundError,
+  EnvNotEnabledForProviderError: () => import_errors.EnvNotEnabledForProviderError,
+  ENV_SLUG_REGEX: () => import_types2.ENV_SLUG_REGEX,
+  BehaviorStore: () => import_store2.BehaviorStore,
+  AmbiguousEnvLabelsError: () => import_errors.AmbiguousEnvLabelsError
 });
 module.exports = __toCommonJS(exports_client);
+var import_store = require("./behaviors/store");
 var import_resource = require("./projectEnvironments/resource");
 var import_resource2 = require("./prompts/resource");
+var import_types = require("./prompts/types");
 var import_resource3 = require("./routingRules/resource");
 var import_transport = require("./transport");
+var import_store2 = require("./behaviors/store");
 var import_errors = require("./errors");
 var import_gateway = require("./gateway");
 var import_resource4 = require("./projectEnvironments/resource");
 var import_resource5 = require("./prompts/resource");
+var import_types2 = require("./prompts/types");
 var import_resource6 = require("./routingRules/resource");
 function createClient(options) {
   const isDomBrowser = typeof globalThis === "object" && typeof globalThis.document !== "undefined";
@@ -80,6 +92,12 @@ function createClient(options) {
   if (options.apiKey !== undefined && options.apiKey.trim() === "") {
     throw new Error("[to11ai/sdk] `apiKey` must not be an empty string.");
   }
+  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.");
+  }
+  if (options.env !== undefined && !import_types.ENV_SLUG_REGEX.test(options.env)) {
+    throw new Error(`[to11ai/sdk] \`env\` must match ${import_types.ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(options.env)}`);
+  }
   const hasApiKey = options.apiKey !== undefined;
   const hasGetAccessToken = options.getAccessToken !== undefined;
   const getAccessToken = options.getAccessToken;
@@ -87,14 +105,29 @@ function createClient(options) {
     throw new Error("[to11ai/sdk] Provide exactly one of `apiKey` (server) or `getAccessToken` (browser).");
   }
   const auth = options.apiKey !== undefined ? { apiKey: options.apiKey } : { getAccessToken };
+  const isBrowser = isDomBrowser || isWorkerBrowser;
+  const processEnv = !isBrowser && typeof process !== "undefined" && typeof process.env === "object" ? process.env : undefined;
+  const behaviorStore = new import_store.BehaviorStore({
+    initOverrides: options.behaviorOverrides,
+    env: processEnv
+  });
   const transport = new import_transport.Transport({
     baseUrl: options.baseUrl,
     auth,
     timeoutMs: options.timeoutMs,
-    maxRetries: options.maxRetries
+    maxRetries: options.maxRetries,
+    behaviorStore
+  });
+  const prompts = new import_resource2.PromptResource(transport, options.cache, {
+    projectId: options.projectId,
+    env: options.env
   });
-  const prompts = new import_resource2.PromptResource(transport, options.cache);
   const projectEnvironments = new import_resource.ProjectEnvironmentResource(transport);
   const routingRules = new import_resource3.RoutingRulesResource(transport);
-  return { prompts, projectEnvironments, routingRules };
+  return {
+    prompts,
+    projectEnvironments,
+    routingRules,
+    resolveBehavior: (key, codedDefault) => behaviorStore.resolve(key, codedDefault)
+  };
 }

package/dist/client.d.ts

@@ -2,14 +2,18 @@ import { ProjectEnvironmentResource } from "./projectEnvironments/resource";
 import type { CacheConfig } from "./prompts/cache";
 import { PromptResource } from "./prompts/resource";
 import { RoutingRulesResource } from "./routingRules/resource";
-export type { NoApplicableRouteReason } from "./errors";
-export { EnvNotEnabledForProviderError, NoApplicableRouteError, PromptLabelNotRegisteredError, RuleNotFoundError, RuleVersionInvalidSnapshotError, To11aiApiError, To11aiAuthError, To11aiError, To11aiNetworkError, To11aiRateLimitError, To11aiValidationError, } from "./errors";
+export { BehaviorStore, type BehaviorStoreOptions, envVarNameForKey, type SdkBehaviorEnvelope, } from "./behaviors/store";
+export type { AmbiguousEnvLabelsReason, EnvNotFoundReason, NoActiveReleaseReason, NoApplicableRouteReason, PromptNotFoundReason, PromptPolicyViolationReason, } from "./errors";
+export { AmbiguousEnvLabelsError, EnvNotEnabledForProviderError, EnvNotFoundError, NoActiveReleaseError, NoApplicableRouteError, PromptLabelNotRegisteredError, PromptNotFoundError, PromptPolicyViolationError, RuleNotFoundError, RuleVersionInvalidSnapshotError, To11aiApiError, To11aiAuthError, To11aiError, To11aiNetworkError, To11aiRateLimitError, To11aiValidationError, } from "./errors";
 export type { GatewayAuthOptions } from "./gateway";
 export { gatewayAuthHeaders, gatewayPromptHeaders } from "./gateway";
 export type { ArchiveProjectEnvironmentInput, ArchiveProjectEnvironmentResult, CreateProjectEnvironmentInput, CreateProjectEnvironmentResult, GetProjectEnvironmentInput, GetProjectEnvironmentResult, ListProjectEnvironmentsInput, ListProjectEnvironmentsResult, LivePointerCounts, ProjectEnvironment, RestoreProjectEnvironmentInput, RestoreProjectEnvironmentResult, UpdateProjectEnvironmentInput, UpdateProjectEnvironmentResult, } 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";
+export type { BlockRenderRecord, FetchedPrompt, FetchPromptOptions, PromptContext, RenderedChatMessage, RenderedPrompt, ResolvedPrompt, ResolvedPromptEnvelope, } from "./prompts/types";
+export { ENV_SLUG_REGEX } from "./prompts/types";
 export type { CreateRuleVersionInput, CreateRuleVersionResult, GetRuleVersionInput, GetRuleVersionResult, ListRuleReleasesInput, ListRuleReleasesResult, ListRuleVersionsInput, ListRuleVersionsResult, RollbackRuleReleaseInput, RollbackRuleReleaseResult, RuleModelBinding, RuleProviderRef, RuleRelease, RuleReleaseActorType, RuleReleaseApprovalStatus, RuleReleaseChangeKind, RuleReleaseStrategy, RuleReleaseWeight, RuleSnapshot, RuleStrategy, RuleVersion, SetRuleReleaseInput, SetRuleReleaseResult, } from "./routingRules/resource";
 export { RoutingRuleReleaseResource, RoutingRulesResource, RoutingRuleVersionResource, } from "./routingRules/resource";
 export type { Transport } from "./transport";
@@ -26,17 +30,52 @@ interface BrowserAuthOptions {
 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>;
 };
 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;
 }
 /**
  * Create a to11ai SDK client.

package/dist/client.js

@@ -1,12 +1,23 @@
 // src/client.ts
+import { BehaviorStore } from "./behaviors/store";
 import { ProjectEnvironmentResource } from "./projectEnvironments/resource";
 import { PromptResource } from "./prompts/resource";
+import { ENV_SLUG_REGEX } from "./prompts/types";
 import { RoutingRulesResource } from "./routingRules/resource";
 import { Transport } from "./transport";
 import {
+  BehaviorStore as BehaviorStore2,
+  envVarNameForKey
+} from "./behaviors/store";
+import {
+  AmbiguousEnvLabelsError,
   EnvNotEnabledForProviderError,
+  EnvNotFoundError,
+  NoActiveReleaseError,
   NoApplicableRouteError,
   PromptLabelNotRegisteredError,
+  PromptNotFoundError,
+  PromptPolicyViolationError,
   RuleNotFoundError,
   RuleVersionInvalidSnapshotError,
   To11aiApiError,
@@ -19,6 +30,7 @@ import {
 import { gatewayAuthHeaders, gatewayPromptHeaders } from "./gateway";
 import { ProjectEnvironmentResource as ProjectEnvironmentResource2 } from "./projectEnvironments/resource";
 import { PromptResource as PromptResource2 } from "./prompts/resource";
+import { ENV_SLUG_REGEX as ENV_SLUG_REGEX2 } from "./prompts/types";
 import {
   RoutingRuleReleaseResource,
   RoutingRulesResource as RoutingRulesResource2,
@@ -35,6 +47,12 @@ function createClient(options) {
   if (options.apiKey !== undefined && options.apiKey.trim() === "") {
     throw new Error("[to11ai/sdk] `apiKey` must not be an empty string.");
   }
+  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.");
+  }
+  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)}`);
+  }
   const hasApiKey = options.apiKey !== undefined;
   const hasGetAccessToken = options.getAccessToken !== undefined;
   const getAccessToken = options.getAccessToken;
@@ -42,20 +60,36 @@ function createClient(options) {
     throw new Error("[to11ai/sdk] Provide exactly one of `apiKey` (server) or `getAccessToken` (browser).");
   }
   const auth = options.apiKey !== undefined ? { apiKey: options.apiKey } : { getAccessToken };
+  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
+    maxRetries: options.maxRetries,
+    behaviorStore
+  });
+  const prompts = new PromptResource(transport, options.cache, {
+    projectId: options.projectId,
+    env: options.env
   });
-  const prompts = new PromptResource(transport, options.cache);
   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)
+  };
 }
 export {
   gatewayPromptHeaders,
   gatewayAuthHeaders,
+  envVarNameForKey,
   createClient,
   To11aiValidationError,
   To11aiRateLimitError,
@@ -69,8 +103,15 @@ export {
   RoutingRuleVersionResource,
   RoutingRuleReleaseResource,
   PromptResource2 as PromptResource,
+  PromptPolicyViolationError,
+  PromptNotFoundError,
   PromptLabelNotRegisteredError,
   ProjectEnvironmentResource2 as ProjectEnvironmentResource,
   NoApplicableRouteError,
-  EnvNotEnabledForProviderError
+  NoActiveReleaseError,
+  EnvNotFoundError,
+  EnvNotEnabledForProviderError,
+  ENV_SLUG_REGEX2 as ENV_SLUG_REGEX,
+  BehaviorStore2 as BehaviorStore,
+  AmbiguousEnvLabelsError
 };

package/dist/errors.cjs

@@ -40,6 +40,7 @@ var __export = (target, all) => {
 var exports_errors = {};
 __export(exports_errors, {
   To11aiValidationError: () => To11aiValidationError,
+  To11aiResponseValidationError: () => To11aiResponseValidationError,
   To11aiRateLimitError: () => To11aiRateLimitError,
   To11aiNetworkError: () => To11aiNetworkError,
   To11aiError: () => To11aiError,
@@ -47,9 +48,14 @@ __export(exports_errors, {
   To11aiApiError: () => To11aiApiError,
   RuleVersionInvalidSnapshotError: () => RuleVersionInvalidSnapshotError,
   RuleNotFoundError: () => RuleNotFoundError,
+  PromptPolicyViolationError: () => PromptPolicyViolationError,
+  PromptNotFoundError: () => PromptNotFoundError,
   PromptLabelNotRegisteredError: () => PromptLabelNotRegisteredError,
   NoApplicableRouteError: () => NoApplicableRouteError,
-  EnvNotEnabledForProviderError: () => EnvNotEnabledForProviderError
+  NoActiveReleaseError: () => NoActiveReleaseError,
+  EnvNotFoundError: () => EnvNotFoundError,
+  EnvNotEnabledForProviderError: () => EnvNotEnabledForProviderError,
+  AmbiguousEnvLabelsError: () => AmbiguousEnvLabelsError
 });
 module.exports = __toCommonJS(exports_errors);
 
@@ -109,6 +115,21 @@ class To11aiNetworkError extends To11aiError {
   }
 }
 
+class To11aiResponseValidationError extends To11aiError {
+  path;
+  issues;
+  constructor(path, zodError, cause) {
+    super(`[to11ai/sdk] Response from ${path} failed schema validation`, {
+      cause
+    });
+    this.name = "To11aiResponseValidationError";
+    this.path = path;
+    const candidate = zodError?.issues;
+    this.issues = Array.isArray(candidate) ? candidate : [];
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
 class PromptLabelNotRegisteredError extends To11aiApiError {
   projectId;
   label;
@@ -175,6 +196,74 @@ class EnvNotEnabledForProviderError extends To11aiApiError {
   }
 }
 
+class PromptNotFoundError extends To11aiApiError {
+  reason;
+  constructor(message, errorCode, reason, details, statusCode = 404) {
+    super(message, statusCode, errorCode, details);
+    this.name = "PromptNotFoundError";
+    this.reason = reason;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  static is(err) {
+    return err instanceof PromptNotFoundError;
+  }
+}
+
+class EnvNotFoundError extends To11aiApiError {
+  reason;
+  constructor(message, reason, details, statusCode) {
+    super(message, statusCode, "ENV_NOT_FOUND", details);
+    this.name = "EnvNotFoundError";
+    this.reason = reason;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  static missing(env) {
+    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) {
+    return err instanceof EnvNotFoundError;
+  }
+}
+
+class NoActiveReleaseError extends To11aiApiError {
+  reason;
+  constructor(message, reason, details, statusCode = 409) {
+    super(message, statusCode, "NO_ACTIVE_RELEASE", details);
+    this.name = "NoActiveReleaseError";
+    this.reason = reason;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  static is(err) {
+    return err instanceof NoActiveReleaseError;
+  }
+}
+
+class PromptPolicyViolationError extends To11aiApiError {
+  reason;
+  constructor(message, reason, details, statusCode = 403) {
+    super(message, statusCode, reason.code, details);
+    this.name = "PromptPolicyViolationError";
+    this.reason = reason;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  static is(err) {
+    return err instanceof PromptPolicyViolationError;
+  }
+}
+
+class AmbiguousEnvLabelsError extends To11aiApiError {
+  reason;
+  constructor(message, reason, details, statusCode = 409) {
+    super(message, statusCode, "AMBIGUOUS_ENV_LABELS", details);
+    this.name = "AmbiguousEnvLabelsError";
+    this.reason = reason;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  static is(err) {
+    return err instanceof AmbiguousEnvLabelsError;
+  }
+}
+
 class RuleVersionInvalidSnapshotError extends To11aiApiError {
   field;
   reason;

package/dist/errors.d.ts

@@ -38,6 +38,19 @@ export declare class To11aiRateLimitError extends To11aiApiError {
 export declare class To11aiNetworkError extends To11aiError {
     constructor(message: string, cause?: unknown);
 }
+/**
+ * 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 declare class To11aiResponseValidationError extends To11aiError {
+    readonly path: string;
+    readonly issues: {
+        message: string;
+        path: (string | number)[];
+    }[];
+    constructor(path: string, zodError: unknown, cause?: unknown);
+}
 /**
  * Thrown when strict-mode rejects a label move for an unregistered label.
  *
@@ -113,6 +126,135 @@ export declare class EnvNotEnabledForProviderError extends To11aiApiError {
     }, details?: unknown);
     static is(err: unknown): err is EnvNotEnabledForProviderError;
 }
+/**
+ * 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 declare class PromptNotFoundError extends To11aiApiError {
+    readonly reason: PromptNotFoundReason;
+    constructor(message: string, errorCode: string, reason: PromptNotFoundReason, details?: unknown, statusCode?: number);
+    static is(err: unknown): err is 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 declare class EnvNotFoundError extends To11aiApiError {
+    readonly reason: EnvNotFoundReason;
+    constructor(message: string, reason: EnvNotFoundReason, details: unknown, statusCode: number);
+    /** Build the client-eager (missing-at-both) variant — no transport call. */
+    static missing(env?: string): EnvNotFoundError;
+    static is(err: unknown): err is 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 declare class NoActiveReleaseError extends To11aiApiError {
+    readonly reason: NoActiveReleaseReason;
+    constructor(message: string, reason: NoActiveReleaseReason, details?: unknown, statusCode?: number);
+    static is(err: unknown): err is 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 declare class PromptPolicyViolationError extends To11aiApiError {
+    readonly reason: PromptPolicyViolationReason;
+    constructor(message: string, reason: PromptPolicyViolationReason, details?: unknown, statusCode?: number);
+    static is(err: unknown): err is 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 declare class AmbiguousEnvLabelsError extends To11aiApiError {
+    readonly reason: AmbiguousEnvLabelsReason;
+    constructor(message: string, reason: AmbiguousEnvLabelsReason, details?: unknown, statusCode?: number);
+    static is(err: unknown): err is AmbiguousEnvLabelsError;
+}
 /**
  * Thrown when version create rejects the snapshot for a structural
  * reason — invalid variant params, malformed `when` clause, illegal