@to11ai/sdk 1.1.0 → 2.0.0-rc.10

package/src/prompts/resource.ts

@@ -1,9 +1,16 @@
-import { z } from "zod";
-import { EnvNotFoundError, To11aiNetworkError } from "../errors";
+import {
+	MissingLabelError,
+	To11aiApiError,
+	To11aiNetworkError,
+} from "../errors";
 import { zResolvedPrompt } from "../generated/zod.gen";
 import type { ApiEnvelope, Transport } from "../transport";
-import type { CacheConfig } from "./cache";
-import { buildCacheKey, buildFetchCacheKey, PromptCache } from "./cache";
+import type {
+	AnthropicRenderedPrompt,
+	OpenAiRenderedPrompt,
+	RenderResult,
+} from "./shape";
+import { shapePrompt } from "./shape";
 import type {
 	ArchivePromptInput,
 	ArchivePromptResult,
@@ -15,8 +22,6 @@ import type {
 	CreatePromptVersionResult,
 	DeleteProjectPromptLabelInput,
 	DeleteProjectPromptLabelResult,
-	FetchedPrompt,
-	FetchPromptOptions,
 	GetProjectPromptLabelInput,
 	GetProjectPromptLabelResult,
 	GetPromptInput,
@@ -40,10 +45,11 @@ import type {
 	PaginatedResult,
 	RenderedChatMessage,
 	RenderedPrompt,
+	RenderFormat,
+	RenderOptions,
 	ResolvedPrompt,
 	ResolvedPromptEnvelope,
-	ResolvePromptInput,
-	ResolvePromptResult,
+	UnknownRoleMode,
 	UpdateProjectPromptLabelInput,
 	UpdateProjectPromptLabelResult,
 	UpdatePromptInput,
@@ -51,13 +57,12 @@ import type {
 } from "./types";
 import { ENV_SLUG_REGEX } from "./types";
 
-// Re-export CacheConfig so callers can import from this module
-export type { CacheConfig } from "./cache";
 export type {
 	ArchivePromptInput,
 	ArchivePromptResult,
 	BlockRenderRecord,
 	ChatMessage,
+	ChatRole,
 	CreateProjectPromptLabelInput,
 	CreateProjectPromptLabelResult,
 	CreatePromptInput,
@@ -66,8 +71,6 @@ export type {
 	CreatePromptVersionResult,
 	DeleteProjectPromptLabelInput,
 	DeleteProjectPromptLabelResult,
-	FetchedPrompt,
-	FetchPromptOptions,
 	GetProjectPromptLabelInput,
 	GetProjectPromptLabelResult,
 	GetPromptInput,
@@ -101,35 +104,21 @@ export type {
 	PromptVersion,
 	RenderedChatMessage,
 	RenderedPrompt,
+	RenderFormat,
+	RenderOptions,
 	ResolvedPrompt,
 	ResolvedPromptEnvelope,
 	ResolvedToolCall,
 	ResolvedToolDefinition,
-	ResolvePromptInput,
-	ResolvePromptResult,
 	RowError,
-	TextChatMessage,
-	TextChatRole,
+	UnknownRoleMode,
 	UpdateProjectPromptLabelInput,
 	UpdateProjectPromptLabelResult,
 	UpdatePromptInput,
 	UpdatePromptResult,
 } from "./types";
 
-const zResolvedPromptLegacy = zResolvedPrompt.pick({
-	promptId: true,
-	versionId: true,
-	version: true,
-	labels: true,
-	contentHash: true,
-	rendered: true,
-	tools: true,
-	toolChoice: true,
-});
-
-const zResolvedPromptEnvelope = zResolvedPrompt
-	.partial({ releaseId: true })
-	.extend({ strategy: z.enum(["single", "weighted"]).optional() });
+const zResolvedPromptEnvelope = zResolvedPrompt.partial({ releaseId: true });
 
 function unwrap<T>(envelope: ApiEnvelope<T>): T {
 	if (envelope.data === null || envelope.data === undefined) {
@@ -143,22 +132,28 @@ function getProjectPromptsPath(projectId: string): string {
 }
 
 /**
- * Project a server `rendered` payload into the `messages` array of the R5
- * `FetchedPrompt` (D5):
- *   - `format: "chat"` → the message array directly.
- *   - `format: "text"` → a single synthesized `{ role: "user", content }`.
+ * Project a server `rendered` payload into the enriched result's `messages`.
+ *
+ * Prompts resolve as chat blocks. The deprecated `text` format is no longer a
+ * first-class case: a non-chat payload throws rather than being silently
+ * coerced (a text prompt is sugar for a single-block chat and is being removed
+ * from the API).
  */
-function renderedToMessages(rendered: RenderedPrompt): RenderedChatMessage[] {
-	if (rendered.format === "chat") {
-		return rendered.messages;
+function renderedToMessages(
+	rendered: ResolvedPrompt["rendered"],
+): RenderedChatMessage[] {
+	if (rendered.format !== "chat") {
+		throw new Error(
+			"[to11ai/sdk] Unsupported non-chat prompt format; author the prompt as chat blocks.",
+		);
 	}
-	return [{ role: "user", content: rendered.text }];
+	return rendered.messages;
 }
 
 /**
- * Normalize the server resolve envelope into the enriched R5 `FetchedPrompt`.
+ * Normalize the server resolve envelope into the enriched `RenderedPrompt`.
  *
- * - `messages` is synthesized from `rendered` via the D5 projection.
+ * - `messages` is derived from the `rendered` chat payload.
  * - `releaseId` is ALWAYS a key: a string when the server sends one, else
  *   explicit `null` (R5 `string | null`).
  * - `variantName` is present IFF the server sent one (i.e. weighted release);
@@ -167,9 +162,10 @@ function renderedToMessages(rendered: RenderedPrompt): RenderedChatMessage[] {
  */
 function normalizeResolvedEnvelope(
 	raw: ResolvedPrompt | ResolvedPromptEnvelope,
-): FetchedPrompt {
+	slug: string,
+): RenderedPrompt {
 	const provenance = raw as ResolvedPromptEnvelope;
-	const result: FetchedPrompt = {
+	const result: RenderedPrompt = {
 		messages: renderedToMessages(raw.rendered),
 		version: raw.version,
 		releaseId: provenance.releaseId ?? null,
@@ -177,8 +173,12 @@ function normalizeResolvedEnvelope(
 		promptId: raw.promptId,
 		versionId: raw.versionId,
 		contentHash: raw.contentHash,
-		labels: raw.labels,
-		rendered: raw.rendered,
+		label: raw.label,
+		// The requested slug — the API resolve envelope does not echo it, so it
+		// is threaded from the `render()` input (TO11-2727). Surfaced as
+		// `x-to11-prompt-slug` for trace readability.
+		slug,
+		modelConfig: provenance.modelConfig,
 	};
 	// `tools` is present IFF the resolved version declares tool definitions; the
 	// wire may send `null` (or omit it) — normalize both to absent so callers
@@ -208,20 +208,26 @@ function normalizeResolvedEnvelope(
 }
 
 /**
- * Lift a caller-supplied offline `fallback` into the enriched `FetchedPrompt`
- * shape (D7), so `fetch()` returns an identical shape on the online and
- * offline paths. An already-enriched `FetchedPrompt` is returned as-is; a
- * legacy `ResolvedPrompt` is lifted (messages synthesized; `releaseId` → its
- * own value or explicit `null`; `blockRenderRecord` → `{}`; `variantName`
- * stays absent).
+ * Lift a caller-supplied offline `fallback` into the returned shape (D7), so
+ * `render()` returns an identical shape on the online and offline paths. The
+ * fallback's own slug is preferred, falling back to the `render()` input when it
+ * carries none, so `x-to11-prompt-slug` is still emitted.
  */
-function liftFallbackToFetched(
-	fallback: ResolvedPrompt | FetchedPrompt,
-): FetchedPrompt {
-	if ("messages" in fallback) {
-		return structuredClone(fallback);
+function liftFallbackToRendered(
+	fallback: RenderedPrompt,
+	slug: string,
+): RenderedPrompt {
+	// Defensive: `fallback` is typed `RenderedPrompt`, but an untyped JS caller,
+	// an `as` cast, or a persisted pre-2.0 `resolve()` result could pass the old
+	// `ResolvedPrompt` shape (no top-level `messages`). Fail loudly rather than
+	// return a malformed result with `undefined` messages.
+	if (!Array.isArray((fallback as { messages?: unknown }).messages)) {
+		throw new Error(
+			"[to11ai/sdk] `fallback` must be a RenderedPrompt (as returned by render()); the legacy resolve() shape is no longer supported.",
+		);
 	}
-	return normalizeResolvedEnvelope(fallback);
+	// `||` (not `??`) so an empty-string slug also falls through to the input.
+	return { ...structuredClone(fallback), slug: fallback.slug || slug };
 }
 
 function getProjectPromptPath(projectId: string, promptId: string): string {
@@ -261,40 +267,70 @@ function buildLabelEventsQuery(input: ListLabelEventsInput): string {
 }
 
 /**
- * Init-time config for the env-aware `fetch()` surface (TO11-980 / S9).
+ * Init-time config for the env-aware `render()` surface (TO11-980 / S9).
  *
  * `projectId` and `env` come from `createClient`. `projectId` is required for
- * `fetch()` (it builds the project-scoped resolve path); `env` is the default
- * serving environment inherited by every `fetch(slug)` call.
+ * `render()` (it builds the project-scoped resolve path); `env` is the default
+ * serving environment inherited by every `render(slug)` call.
  */
 export interface PromptResourceConfig {
-	/** Project the client is bound to. Required for `fetch()`; validated at createClient. */
+	/** Project the client is bound to. Required for `render()`; validated at createClient. */
 	projectId?: string;
-	/** Default serving env for `fetch()`. Validated against ENV_SLUG_REGEX at createClient. */
+	/** Default serving env for `render()`. Validated against ENV_SLUG_REGEX at createClient. */
 	env?: string;
+	/** Default provider shape for `render()` output. Per-call override allowed. */
+	format?: RenderFormat;
+	/**
+	 * Default unknown-role policy for `render({ format })` output conversion.
+	 * Per-call override allowed; defaults to `"drop"`.
+	 */
+	onUnknownRole?: UnknownRoleMode;
 }
 
-export class PromptResource {
+export class PromptResource<F extends RenderFormat | undefined = undefined> {
 	private readonly transport: Transport;
-	private readonly cache: PromptCache;
 	private readonly projectId: string | undefined;
 	private readonly env: string | undefined;
+	private readonly format: RenderFormat | undefined;
+	private readonly onUnknownRole: UnknownRoleMode | undefined;
 
 	constructor(
 		transport: Transport,
-		cacheConfig?: CacheConfig,
-		config?: PromptResourceConfig,
+		// `format` is bound to the class generic `F` (not the wider `RenderFormat`)
+		// so the constructed default shape cannot disagree with what `render()`'s
+		// return type (`RenderResult<F>`) promises.
+		config?: Omit<PromptResourceConfig, "format"> & { format?: F },
 	) {
 		this.transport = transport;
-		this.cache = new PromptCache(cacheConfig);
 		this.projectId = config?.projectId;
 		this.env = config?.env;
+		this.format = config?.format;
+		this.onUnknownRole = config?.onUnknownRole;
+	}
+
+	/**
+	 * Resolve the project for a control-plane call: the per-call `projectId`
+	 * wins, else the client-bound one from `createClient({ projectId })`. Throws
+	 * if neither is set. Mirrors how `render()` resolves its project, so every
+	 * method honors the bound `projectId` and callers need not repeat it.
+	 */
+	private resolveProjectId(perCall?: string): string {
+		const projectId = perCall ?? this.projectId;
+		if (projectId === undefined || projectId.trim() === "") {
+			throw new Error(
+				"[to11ai/sdk] this call needs a `projectId` — pass it on the call or bind one via createClient({ projectId, ... }).",
+			);
+		}
+		// Trim so a whitespace-padded per-call id normalizes like the client-bound
+		// one (resolved via `pick()`), instead of reaching the wire untrimmed.
+		return projectId.trim();
 	}
 
 	// ─── Create ──────────────────────────────────────────────────────────────
 
 	async create(input: CreatePromptInput): Promise<CreatePromptResult> {
-		const { projectId, ...body } = input;
+		const { projectId: perCallProjectId, ...body } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope = await this.transport.request<CreatePromptResult>(
 			"POST",
 			getProjectPromptsPath(projectId),
@@ -306,9 +342,10 @@ export class PromptResource {
 	// ─── List ─────────────────────────────────────────────────────────────────
 
 	async list(
-		input: ListPromptsInput,
+		input: ListPromptsInput = {},
 	): Promise<PaginatedResult<ListPromptsResult>> {
-		const { projectId, ...queryRest } = input;
+		const { projectId: perCallProjectId, ...queryRest } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope = await this.transport.request<
 			| ListPromptsResult[]
 			| {
@@ -340,7 +377,8 @@ export class PromptResource {
 	// ─── Get ──────────────────────────────────────────────────────────────────
 
 	async get(input: GetPromptInput): Promise<GetPromptResult> {
-		const { projectId, promptId } = input;
+		const { projectId: perCallProjectId, promptId } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope = await this.transport.request<GetPromptResult>(
 			"GET",
 			getProjectPromptPath(projectId, promptId),
@@ -351,7 +389,8 @@ export class PromptResource {
 	// ─── Update ───────────────────────────────────────────────────────────────
 
 	async update(input: UpdatePromptInput): Promise<UpdatePromptResult> {
-		const { projectId, promptId, ...body } = input;
+		const { projectId: perCallProjectId, promptId, ...body } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope = await this.transport.request<UpdatePromptResult>(
 			"PATCH",
 			getProjectPromptPath(projectId, promptId),
@@ -363,7 +402,8 @@ export class PromptResource {
 	// ─── Archive ──────────────────────────────────────────────────────────────
 
 	async archive(input: ArchivePromptInput): Promise<ArchivePromptResult> {
-		const { projectId, promptId } = input;
+		const { projectId: perCallProjectId, promptId } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope = await this.transport.request<ArchivePromptResult>(
 			"DELETE",
 			getProjectPromptPath(projectId, promptId),
@@ -376,7 +416,8 @@ export class PromptResource {
 	async createVersion(
 		input: CreatePromptVersionInput,
 	): Promise<CreatePromptVersionResult> {
-		const { projectId, promptId, ...body } = input;
+		const { projectId: perCallProjectId, promptId, ...body } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope = await this.transport.request<CreatePromptVersionResult>(
 			"POST",
 			`${getProjectPromptPath(projectId, promptId)}/versions`,
@@ -390,7 +431,8 @@ export class PromptResource {
 	async listVersions(
 		input: ListPromptVersionsInput,
 	): Promise<ListPromptVersionsResult> {
-		const { projectId, promptId } = input;
+		const { projectId: perCallProjectId, promptId } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope = await this.transport.request<ListPromptVersionsResult>(
 			"GET",
 			`${getProjectPromptPath(projectId, promptId)}/versions`,
@@ -403,7 +445,8 @@ export class PromptResource {
 	async getVersion(
 		input: GetPromptVersionInput,
 	): Promise<GetPromptVersionResult> {
-		const { projectId, promptId, versionNumber } = input;
+		const { projectId: perCallProjectId, promptId, versionNumber } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope = await this.transport.request<GetPromptVersionResult>(
 			"GET",
 			`${getProjectPromptPath(projectId, promptId)}/versions/${encodeURIComponent(String(versionNumber))}`,
@@ -414,7 +457,8 @@ export class PromptResource {
 	// ─── Move Label ───────────────────────────────────────────────────────────
 
 	async moveLabel(input: MovePromptLabelInput): Promise<MovePromptLabelResult> {
-		const { projectId, promptId, label, ...body } = input;
+		const { projectId: perCallProjectId, promptId, label, ...body } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope = await this.transport.request<MovePromptLabelResult>(
 			"PUT",
 			`${getProjectPromptPath(projectId, promptId)}/labels/${encodeURIComponent(label)}`,
@@ -428,7 +472,8 @@ export class PromptResource {
 	async listLabels(
 		input: ListPromptLabelsInput,
 	): Promise<ListPromptLabelsResult> {
-		const { projectId, promptId } = input;
+		const { projectId: perCallProjectId, promptId } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope = await this.transport.request<ListPromptLabelsResult>(
 			"GET",
 			`${getProjectPromptPath(projectId, promptId)}/labels`,
@@ -436,90 +481,94 @@ export class PromptResource {
 		return unwrap(envelope);
 	}
 
-	// ─── Fetch (env-aware resolution, TO11-980 / S9) ──────────────────────────
+	// ─── Render (env-aware resolution + format shaping, TO11-980 / TO11-2691) ──
 
 	/**
-	 * Resolve a prompt for the client's configured `projectId` + `env`
-	 * (Style-A). The ergonomic slug-first surface: env is configured once at
-	 * `createClient` and inherited here, with an optional per-call override.
+	 * Resolve and (optionally) shape a prompt for the client's configured
+	 * `projectId` + `env`, in one control-plane request. With a `format` (per
+	 * call or inherited from the client) the result is provider-shaped
+	 * `{ messages, config, metadata }`; without one it is the neutral
+	 * `RenderedPrompt`. Resolves by the client's configured `env`.
 	 *
-	 * - **env→label wire mapping (correction #3):** the resolve route is
-	 *   label-based (`/v1/projects/:projectId/prompts:resolve`, body
-	 *   `labels[]`); it does NOT accept a top-level `env` field. The resolved
-	 *   env slug (lowercase-kebab — a valid label name) is therefore sent as
-	 *   the single resolution label: body `{ slug, labels: [env], subject?,
-	 *   variables? }`.
-	 * - **No silent fallback (R4):** if no env is resolvable (none at init AND
-	 *   none per call) this throws `EnvNotFoundError` (`reason.source =
-	 *   "missing"`) CLIENT-side, eagerly, before any transport call.
-	 * - **Cache (D8):** caches `single`-strategy releases and weighted releases
-	 *   WITH a `subject`; BYPASSES the cache for weighted releases with NO
-	 *   `subject` (a uniform-random assignment must not be pinned for the TTL).
+	 * @example Render an OpenAI-shaped prompt and send it through the gateway
+	 * const prompt = await to11.prompts.render("weather-concierge", {
+	 *   variables: { city: "NYC" },
+	 * });
+	 * const res = await openai.chat.completions.create(
+	 *   { ...prompt.config, messages: prompt.messages },
+	 *   { headers: to11.turn().headers(prompt) },
+	 * );
+	 */
+	async render(
+		slug: string,
+		options: RenderOptions & { format: "openai" },
+	): Promise<OpenAiRenderedPrompt>;
+	async render(
+		slug: string,
+		options: RenderOptions & { format: "anthropic" },
+	): Promise<AnthropicRenderedPrompt>;
+	async render(slug: string, options?: RenderOptions): Promise<RenderResult<F>>;
+	async render(
+		slug: string,
+		options: RenderOptions = {},
+	): Promise<RenderedPrompt | OpenAiRenderedPrompt | AnthropicRenderedPrompt> {
+		const rendered = await this.resolveToRendered(slug, options);
+		return shapePrompt(rendered, options.format ?? this.format, {
+			onUnknownRole: options.onUnknownRole ?? this.onUnknownRole,
+		});
+	}
+
+	/**
+	 * Env-aware resolution → neutral `RenderedPrompt`. Carries the resolve /
+	 * offline-fallback logic; `render()` is the public shaping surface.
 	 *
-	 * Prefer this over the deprecated `resolve()`.
+	 * - **wire mapping (TO11-2743):** posts to the path-addressed render route
+	 *   (`/v1/projects/:projectId/prompts/by-slug/:slug/labels/:label/render`),
+	 *   body `{ variables? }`. The resolved label is the single path label.
+	 * - **No silent fallback (R4):** if no label is resolvable (none per call
+	 *   AND no client `env` fallback) this throws `MissingLabelError`
+	 *   CLIENT-side, eagerly, before any transport call.
 	 */
-	async fetch(
+	private async resolveToRendered(
 		slug: string,
-		options: FetchPromptOptions = {},
-	): Promise<FetchedPrompt> {
+		options: RenderOptions = {},
+	): Promise<RenderedPrompt> {
 		if (this.projectId === undefined || this.projectId.trim() === "") {
 			throw new Error(
-				"[to11ai/sdk] `prompts.fetch()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).",
+				"[to11ai/sdk] `prompts.render()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).",
 			);
 		}
 
-		// R2 precedence: per-call env > init-time env. No third source.
-		const env = options.env ?? this.env;
+		// R2 precedence: per-call label > client `env` fallback. No third source.
+		const label = options.label ?? this.env;
 
-		// R4 / AC4: no env resolvable → throw eagerly, ZERO transport calls.
-		if (env === undefined) {
-			throw EnvNotFoundError.missing();
+		// R4 / AC4: no label resolvable → throw eagerly, ZERO transport calls.
+		if (label === undefined) {
+			throw new MissingLabelError();
 		}
 
-		// Validate the RESOLVED env (per-call OR init). createClient validates the
-		// init-time env, but PromptResource has a public constructor that can
-		// bypass createClient, so re-validate here so a malformed env (e.g.
-		// "Prod") never reaches the wire as a resolution label (CodeRabbit).
-		if (!ENV_SLUG_REGEX.test(env)) {
+		// Validate the RESOLVED label (per-call OR the client `env` fallback).
+		// createClient validates the init-time env, but PromptResource has a
+		// public constructor that can bypass createClient, so re-validate here so
+		// a malformed label (e.g. "Prod") never reaches the wire (CodeRabbit).
+		if (!ENV_SLUG_REGEX.test(label)) {
 			throw new Error(
-				`[to11ai/sdk] \`env\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(env)}`,
+				`[to11ai/sdk] \`label\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(label)}`,
 			);
 		}
 
-		const {
-			subject,
-			variables,
-			cache: useCache = true,
-			fallback,
-			developerRole,
-		} = options;
-
-		const cacheKey = buildFetchCacheKey(
-			this.projectId,
-			slug,
-			env,
-			subject,
-			variables,
-			developerRole,
-		);
-
-		if (useCache) {
-			const cached = this.cache.get(cacheKey);
-			// Only enriched (fetch) entries are valid hits here; the fetch key
-			// namespace ("fetch|…") never collides with the legacy resolve key.
-			if (cached && "messages" in cached) return structuredClone(cached);
-		}
+		const { variables, fallback } = options;
 
-		// env→label mapping: the env slug is the single resolution label.
-		const body: Record<string, unknown> = { slug, labels: [env] };
-		if (subject !== undefined) body.subject = subject;
+		// TO11-2743: slug + the single resolved label live in the PATH; the body
+		// carries only `variables`. Weighted-release bucketing (`subject`) is not
+		// supported by the render endpoint yet, so it's dropped from the surface.
+		const body: Record<string, unknown> = {};
 		if (variables !== undefined) body.variables = variables;
-		if (developerRole !== undefined) body.developerRole = developerRole;
 
 		try {
 			const envelope = await this.transport.request<ResolvedPromptEnvelope>(
 				"POST",
-				`${getProjectPromptsPath(this.projectId)}:resolve`,
+				`${getProjectPromptsPath(this.projectId)}/by-slug/${encodeURIComponent(slug)}/labels/${encodeURIComponent(label)}/render`,
 				{
 					body,
 					decode: (data) =>
@@ -527,88 +576,17 @@ export class PromptResource {
 				},
 			);
 			const raw = unwrap(envelope);
-			const result = normalizeResolvedEnvelope(raw);
-
-			// D8: bypass the cache for a weighted release with NO subject —
-			// caching a uniform-random assignment would pin one variant for the
-			// whole TTL. Cache `single` releases and `subject`-keyed weighted
-			// releases (deterministic, safe to cache). Weighted-ness is inferred
-			// from `strategy === "weighted"` OR the presence of `variantName`
-			// (which the server stamps iff weighted) — so a result that carries a
-			// variant but omits `strategy` is still correctly bypassed rather than
-			// pinning one random variant for the TTL (Cursor / Greptile).
-			const isWeighted =
-				raw.strategy === "weighted" || result.variantName !== undefined;
-			const cacheable = !(isWeighted && subject === undefined);
-			if (useCache && cacheable) {
-				this.cache.set(cacheKey, structuredClone(result));
-			}
-
-			return result;
-		} catch (err) {
-			// D7: offline fallback is consulted ONLY on a network outage with an
-			// empty cache. A server `ENV_NOT_FOUND` is a typed application error
-			// (not a To11aiNetworkError), so it bypasses this branch. R4's
-			// client-eager throw already happened above the try, so there is no
-			// network error to trigger it on the env-missing path.
-			if (err instanceof To11aiNetworkError && fallback !== undefined) {
-				return liftFallbackToFetched(fallback);
-			}
-			throw err;
-		}
-	}
-
-	// ─── Resolve ──────────────────────────────────────────────────────────────
-
-	/**
-	 * @deprecated Use {@link PromptResource.fetch | `prompts.fetch(slug,
-	 * options?)`} instead. `resolve()` is env-agnostic (no `env` / `subject`,
-	 * no enriched release/variant provenance, no typed-env errors)
-	 * and is retained only for back-compat. It is NOT subject to the R4
-	 * no-silent-fallback env gate (it has no env concept). New code should
-	 * configure `projectId` + `env` at `createClient` and call `fetch()`.
-	 */
-	async resolve(input: ResolvePromptInput): Promise<ResolvePromptResult> {
-		const {
-			projectId,
-			slug,
-			labels,
-			variables,
-			cache: useCache = true,
-			fallback,
-		} = input;
-
-		const cacheKey = buildCacheKey(projectId, slug, labels, variables);
-
-		if (useCache) {
-			const cached = this.cache.get(cacheKey);
-			// The legacy resolve key namespace only ever stores ResolvedPrompt
-			// entries (the fetch namespace is "fetch|…"); the `messages` guard
-			// keeps the static return type as ResolvedPrompt.
-			if (cached && !("messages" in cached)) return structuredClone(cached);
-		}
-
-		try {
-			const envelope = await this.transport.request<ResolvePromptResult>(
-				"POST",
-				`${getProjectPromptsPath(projectId)}:resolve`,
-				{
-					body: { slug, labels, variables },
-					decode: (data) =>
-						zResolvedPromptLegacy.parse(data) as ResolvePromptResult,
-				},
-			);
-			const result = unwrap(envelope);
-
-			if (useCache) {
-				this.cache.set(cacheKey, structuredClone(result));
-			}
-
-			return result;
+			return normalizeResolvedEnvelope(raw, slug);
 		} catch (err) {
-			// If network error and we have a fallback, serve it
-			if (err instanceof To11aiNetworkError && fallback !== undefined) {
-				return fallback;
+			// Serve the offline fallback on a TRANSIENT outage — a network error
+			// or a 5xx from the control plane. A typed 4xx (not-found / policy /
+			// validation) is a real application error and is NOT masked. The
+			// client-eager MissingLabelError already threw above the try.
+			const transient =
+				err instanceof To11aiNetworkError ||
+				(err instanceof To11aiApiError && err.statusCode >= 500);
+			if (transient && fallback !== undefined) {
+				return liftFallbackToRendered(fallback, slug);
 			}
 			throw err;
 		}
@@ -624,9 +602,10 @@ export class PromptResource {
 	 * affordances). Gated on `prompt:read` server-side.
 	 */
 	async listProjectLabels(
-		input: ListProjectPromptLabelsInput,
+		input: ListProjectPromptLabelsInput = {},
 	): Promise<ListProjectPromptLabelsResult> {
-		const { projectId, includeArchived } = input;
+		const { projectId: perCallProjectId, includeArchived } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope =
 			await this.transport.request<ListProjectPromptLabelsResult>(
 				"GET",
@@ -648,7 +627,8 @@ export class PromptResource {
 	async createProjectLabel(
 		input: CreateProjectPromptLabelInput,
 	): Promise<CreateProjectPromptLabelResult> {
-		const { projectId, ...body } = input;
+		const { projectId: perCallProjectId, ...body } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const envelope =
 			await this.transport.request<CreateProjectPromptLabelResult>(
 				"POST",
@@ -661,9 +641,10 @@ export class PromptResource {
 	async getProjectLabel(
 		input: GetProjectPromptLabelInput,
 	): Promise<GetProjectPromptLabelResult> {
+		const projectId = this.resolveProjectId(input.projectId);
 		const envelope = await this.transport.request<GetProjectPromptLabelResult>(
 			"GET",
-			getProjectPromptLabelPath(input.projectId, input.label),
+			getProjectPromptLabelPath(projectId, input.label),
 		);
 		return unwrap(envelope);
 	}
@@ -679,7 +660,8 @@ export class PromptResource {
 	async updateProjectLabel(
 		input: UpdateProjectPromptLabelInput,
 	): Promise<UpdateProjectPromptLabelResult> {
-		const { projectId, label, ...rest } = input;
+		const { projectId: perCallProjectId, label, ...rest } = input;
+		const projectId = this.resolveProjectId(perCallProjectId);
 		const body: Record<string, unknown> = {};
 		if (rest.isDefault !== undefined) body.isDefault = rest.isDefault;
 		if (rest.description !== undefined) body.description = rest.description;
@@ -705,10 +687,11 @@ export class PromptResource {
 	async deleteProjectLabel(
 		input: DeleteProjectPromptLabelInput,
 	): Promise<DeleteProjectPromptLabelResult> {
+		const projectId = this.resolveProjectId(input.projectId);
 		const envelope =
 			await this.transport.request<DeleteProjectPromptLabelResult>(
 				"DELETE",
-				getProjectPromptLabelPath(input.projectId, input.label),
+				getProjectPromptLabelPath(projectId, input.label),
 			);
 		return unwrap(envelope);
 	}
@@ -727,7 +710,7 @@ export class PromptResource {
 		const envelope =
 			await this.transport.request<ListProjectPromptLabelUsagesResult>(
 				"GET",
-				`${getProjectPromptLabelPath(input.projectId, input.label)}/usages`,
+				`${getProjectPromptLabelPath(this.resolveProjectId(input.projectId), input.label)}/usages`,
 			);
 		return unwrap(envelope);
 	}
@@ -752,7 +735,9 @@ export class PromptResource {
 	async listLabelEvents(
 		input: ListLabelEventsInput,
 	): Promise<ListLabelEventsResult> {
-		const projectSeg = encodeURIComponent(input.projectId);
+		const projectSeg = encodeURIComponent(
+			this.resolveProjectId(input.projectId),
+		);
 		let path: string;
 		switch (input.scope) {
 			case "label":