@apifuse/provider-sdk 2.2.0-beta.62 → 2.2.0-beta.63

package/dist/server/types.d.ts

@@ -38,6 +38,7 @@ export declare const OperationRequestSchema: z.ZodObject<{
         metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         externalRef: z.ZodString;
     }, z.core.$strip>>;
+    tenantId: z.ZodOptional<z.ZodString>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     trace: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;

package/dist/server/types.js

@@ -21,6 +21,13 @@ export const OperationRequestSchema = z.object({
     input: z.record(z.string(), z.unknown()),
     connectionId: z.string().optional(),
     connection: OperationConnectionSchema.optional(),
+    /**
+     * Gateway-asserted principal scope: the organization id for customer
+     * subjects, the service-account id for platform service accounts. Absent
+     * on direct calls and self-test. Trusted exactly like `connectionId`; it is
+     * never derived from caller headers or `input`.
+     */
+    tenantId: z.string().optional(),
     headers: z.record(z.string(), z.string()).optional(),
     trace: z.record(z.string(), z.string()).optional(),
 });

package/dist/stateful/stateful-provider-owner-forwarder.js

@@ -145,6 +145,7 @@ function buildForwardingEnvelope(input) {
             requestId: input.request.requestId,
             input: input.request.input,
             connection: metadata.connection,
+            ...(metadata.tenantId ? { tenantId: metadata.tenantId } : {}),
             headers: sanitizeForwardedHeaders(metadata.headers),
             ...(metadata.trace ? { trace: metadata.trace } : {}),
         },
@@ -160,12 +161,33 @@ function forwardedMetadata(request) {
     }
     const operationRequest = forwardingContext.operationRequest;
     const connection = OperationConnectionSchema.parse(operationRequest?.connection);
+    const tenantId = forwardedTenantId(operationRequest?.tenantId);
     return {
         connection,
+        ...(tenantId !== undefined ? { tenantId } : {}),
         ...(operationRequest?.headers ? { headers: operationRequest.headers } : {}),
         ...(operationRequest?.trace ? { trace: operationRequest.trace } : {}),
     };
 }
+/**
+ * The runtime context is consumer-supplied and typed `unknown`, and only its
+ * `requestId` is guarded on read. A malformed principal scope must fail at the
+ * source with a forwarding error — the owner would otherwise reject the whole
+ * forwarded operation, and dropping it silently would downgrade a per-principal
+ * policy to the shared scope. `""` is not a principal (same rule as ids on the
+ * ingress envelope), so it is absent rather than invalid.
+ */
+function forwardedTenantId(value) {
+    if (value === undefined || value === "")
+        return undefined;
+    if (typeof value !== "string") {
+        throw new StatefulOwnerForwardingError({
+            code: "STATEFUL_FORWARDING_CONTEXT_INVALID",
+            message: "Stateful operation forwarding requires a string tenantId when it is present.",
+        });
+    }
+    return value;
+}
 function sanitizeForwardedHeaders(headers) {
     if (!headers)
         return {};

package/dist/stateful/stateful-provider-runtime-context.d.ts

@@ -5,6 +5,8 @@ export interface StatefulForwardingRuntimeContext {
     readonly operationRequest?: {
         readonly requestId: string;
         readonly connection?: unknown;
+        /** Gateway-asserted principal scope; forwarded verbatim to the owner pod. */
+        readonly tenantId?: string;
         readonly headers?: Record<string, string>;
         readonly trace?: Record<string, string>;
     };
@@ -24,6 +26,7 @@ export declare function withStatefulLocalProviderContext(providerContext: unknow
 export declare function statefulForwardingContextFromProviderRequest(request: {
     readonly requestId: string;
     readonly connection?: unknown;
+    readonly tenantId?: string;
     readonly headers?: Record<string, string>;
     readonly trace?: Record<string, string>;
 }): StatefulForwardingRuntimeContext;

package/dist/stateful/stateful-provider-runtime-context.js

@@ -16,6 +16,7 @@ export function statefulForwardingContextFromProviderRequest(request) {
         operationRequest: {
             requestId: request.requestId,
             ...(request.connection !== undefined ? { connection: request.connection } : {}),
+            ...(request.tenantId ? { tenantId: request.tenantId } : {}),
             ...(request.headers ? { headers: request.headers } : {}),
             ...(request.trace ? { trace: request.trace } : {}),
         },

package/dist/types.d.ts

@@ -782,8 +782,17 @@ export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number
 export interface OperationErrorCode {
     code: string;
     status?: ProviderErrorStatus;
+    /** Developer-facing English prose for docs and MCP tool text. Never localized. */
     description: string;
     retryable?: boolean;
+    /**
+     * Locale catalog key for the client-facing `message` of every error thrown
+     * with this `code`. A throw site's own `messageKey` wins; when neither is
+     * present the SDK derives `errors.<code>.message`.
+     */
+    messageKey?: ProviderLocaleKeyInput;
+    /** Locale catalog key for the client-facing `fix`. Derived default: `errors.<code>.fix`. */
+    fixKey?: ProviderLocaleKeyInput;
 }
 export type StealthPlatform = "macos" | "windows" | "linux" | "android" | "ios";
 export type StealthBrowser = "chrome" | "firefox" | "safari";
@@ -1039,8 +1048,44 @@ export interface HttpRetrySummary {
     lastErrorCode?: string;
     lastStatus?: number;
 }
+/** Per-attempt input for a `RequestOptions.headers` factory. */
+export interface HttpAttemptContext {
+    /**
+     * 1-based number of this request build: the first request is `1`, its first
+     * retry `2`. Only attempts that reach header resolution count; a failed
+     * proxy allocation or a skipped duplicate proxy offset builds no request
+     * and is not numbered.
+     */
+    attempt: number;
+    /**
+     * Resolved request URL: `baseUrl` + path + `params` + `sensitiveParams`.
+     * It is the exact URL the attempt is issued against, so bind signature
+     * targets to it rather than to a URL the caller rebuilds. Strip the query
+     * and fragment for fields that are defined without them — RFC 9449 §4.2
+     * requires that of DPoP `htu`. It carries any sensitive query values, so
+     * never log it and never copy it verbatim into a signed field that a
+     * verifier logs.
+     */
+    url: string;
+    /** Normalized upper-case HTTP method of the request. */
+    method: Uppercase<HttpMethod>;
+}
+/**
+ * Builds the request headers for one issued attempt. Managed retry calls it
+ * again for every retry, so request-bound single-use proofs (DPoP `jti`,
+ * HTTP message signatures, HMAC nonces) can be re-minted instead of replayed.
+ * A throw is raised as a non-retryable `TransportError` with code
+ * `http_header_factory_failed`.
+ */
+export type HttpHeadersFactory = (attempt: HttpAttemptContext) => Record<string, string> | Promise<Record<string, string>>;
 export interface RequestOptions {
-    headers?: Record<string, string>;
+    /**
+     * Request headers, or a factory resolved once per issued attempt (see
+     * `HttpHeadersFactory`). The factory runs after proxy resolution, before the
+     * first redirect hop of that attempt; redirect hops reuse the attempt's
+     * headers. `ctx.stealth` declares its own header option and is not affected.
+     */
+    headers?: Record<string, string> | HttpHeadersFactory;
     params?: RequestParams;
     /**
      * Query parameters whose values contain credentials or other secret material.
@@ -1048,7 +1093,23 @@ export interface RequestOptions {
      */
     sensitiveParams?: Record<string, string>;
     proxy?: string;
+    /**
+     * Per-attempt timeout for the response-header phase. It is disarmed once a
+     * successful response's headers arrive, so it never bounds consumption of
+     * that body — on the buffered path as well as on streams; use `signal` for
+     * that. A non-2xx body the transport discards on the caller's behalf is
+     * still drained under this deadline, so a wedged error body cannot hang the
+     * attempt.
+     */
     timeout?: number;
+    /**
+     * Cancels this request only — its retries, its backoff sleep and its
+     * response-body consumption — leaving the client's other in-flight requests
+     * untouched. Merged with the client-level `signal`, so a rejection reads as
+     * `transport_cancelled` either way; inspect `signal.reason` to tell a
+     * per-request abort from a fleet-wide one.
+     */
+    signal?: AbortSignal;
     /**
      * Defaults to true. Set to false when callers need to inspect upstream
      * non-2xx bodies themselves instead of converting them to TransportError.
@@ -1073,6 +1134,13 @@ export interface HttpRedirectPolicy {
 export type HttpRedirectFailureReason = Exclude<RedirectRunReason, "completed">;
 export type HttpMethod = "HEAD" | "head" | "GET" | "get" | "POST" | "post" | "PUT" | "put" | "DELETE" | "delete" | "OPTIONS" | "options" | "TRACE" | "trace" | "PATCH" | "patch";
 export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy" | "headers"> {
+    /**
+     * Not supported by the stealth transport, which observes only the
+     * client-level `signal` passed to `createStealthClient`. Typed as `never` so
+     * a per-request signal fails to compile instead of being silently ignored;
+     * threading one through the stealth session is a separate change.
+     */
+    signal?: never;
     /**
      * Defaults to true. Set to false when callers need to inspect upstream
      * non-2xx bodies themselves instead of converting them to TransportError.
@@ -1659,6 +1727,16 @@ export interface CredentialContext {
 }
 export interface ProviderRequestContext {
     connectionId?: string;
+    /**
+     * Gateway-asserted principal scope of the operation request: the
+     * organization id for customer subjects, the service-account id for
+     * platform service accounts. `undefined` on direct calls and self-test
+     * (unlike `FlowContext.tenantId`, which is coerced to `""`); an empty
+     * string on the wire is normalised to `undefined` like `connectionId`.
+     * Key per-principal policy (quota, fairness, correlation) for
+     * connectionless operations on it. It does not scope `ctx.state`.
+     */
+    tenantId?: string;
     headers: Record<string, string>;
 }
 export interface ContextScratchpad {
@@ -1915,10 +1993,17 @@ export interface AuthConfig {
     proxied?: ProxiedOAuthConfig;
     flow?: AuthFlowDefinition;
 }
+/** Who provisions a declared secret: the platform (`apifuse`) or the provider author (`contributor`). */
+export type ProviderSecretIssuer = "apifuse" | "contributor";
 export interface ProviderSecretDeclaration {
     name: string;
     description?: string;
     required?: boolean;
+    /**
+     * Optional today; ADR-0011 D3 makes it required once every deployed provider
+     * declares it. Metadata only: it does not change which secrets are projected.
+     */
+    issuer?: ProviderSecretIssuer;
 }
 export interface CredentialDeclaration {
     keys: string[];
@@ -2000,6 +2085,14 @@ export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOu
  * optional. Note that the deployment `runtime` axis
  * (`shared`/`dedicated`/`browser`) is distinct from the provider execution
  * `runtime` (`standard`/`shared`/`browser`).
+ *
+ * This key is the ONLY authored deployment surface. Declare it inside the
+ * `defineProvider({...})` literal, not on a spread default export and not
+ * in a standalone `deploy.ts` (legacy; `apifuse migrate-deployment` hoists
+ * and deletes it). Write only what differs from the runtime profile —
+ * shared `25m/128Mi`, browser `200m/256Mi`, `language: "typescript"`,
+ * `replicas: 1`, HPA enabled 1-1 at 70% CPU — so most providers declare
+ * nothing and `apifuse check` warns on restated defaults.
  */
 export interface ProviderDeploymentOverrides {
     runtime?: "shared" | "dedicated" | "browser";

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.62",
+	"version": "2.2.0-beta.63",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -15,9 +15,14 @@
 		"src",
 		"!src/__tests__",
 		"!src/__tests__/**",
+		"!src/**/__tests__",
+		"!src/**/__tests__/**",
 		"!src/**/*.test.ts",
+		"!src/**/*.spec.ts",
 		"!src/index.test.ts",
 		"bin",
+		"!bin/__tests__",
+		"!bin/__tests__/**",
 		"README.md",
 		"AUTHORING.md",
 		"CHANGELOG.md",

package/src/cli/commands.ts

@@ -5,6 +5,7 @@ export type ApifuseCommandName =
 	| "sync-assets"
 	| "migrate-shape"
 	| "migrate-operation-declaration"
+	| "migrate-deployment"
 	| "submit-check"
 	| "bounty-check"
 	| "record"
@@ -76,6 +77,18 @@ export const COMMAND_MANIFEST: Record<
 		],
 		modulePath: "./apifuse-migrate-operation-declaration",
 	},
+	"migrate-deployment": {
+		name: "migrate-deployment",
+		summary:
+			"Retire a legacy deploy.ts: hoist its non-default values into the defineProvider() deployment key and delete the file.",
+		usage:
+			"apifuse migrate-deployment [path] [--check] [--json] [--drop-codeowners-lock]",
+		examples: [
+			"apifuse migrate-deployment .",
+			"apifuse migrate-deployment . --check --json",
+		],
+		modulePath: "./apifuse-migrate-deployment",
+	},
 	"submit-check": {
 		name: "submit-check",
 		summary:
@@ -136,6 +149,7 @@ export const COMMAND_ORDER: ApifuseCommandName[] = [
 	"sync-assets",
 	"migrate-shape",
 	"migrate-operation-declaration",
+	"migrate-deployment",
 	"submit-check",
 	"record",
 	"test",

package/src/cli/deployment-intent.ts

@@ -0,0 +1,364 @@
+import { z } from "zod";
+
+import type { ProviderDeploymentOverrides } from "../types.js";
+
+/**
+ * Deployment-intent helpers shared by `apifuse check` and
+ * `apifuse migrate-deployment`.
+ *
+ * Deployment intent has exactly one authored home: the optional `deployment`
+ * key on `defineProvider()`. The APIFuse registry builder is the only reader;
+ * it resolves omitted fields from a runtime profile and rejects anything it
+ * cannot resolve. This module mirrors that profile table so the CLI can
+ * (a) subtract profile defaults when hoisting a legacy `deploy.ts` into the
+ * key and (b) warn when a declared key restates a default. The registry
+ * stays canonical — keep the constants below identical to
+ * `resolveProviderDeploymentConfig` in `@apifuse/provider-registry`.
+ */
+
+export type DeploymentRuntime = "shared" | "dedicated" | "browser";
+export type DeploymentLanguage = "typescript" | "python";
+
+export interface DeploymentResources {
+	cpu: string;
+	memory: string;
+}
+
+export interface DeploymentHpa {
+	enabled: boolean;
+	minReplicas?: number;
+	maxReplicas?: number;
+	targetCPUUtilizationPercentage?: number;
+}
+
+/** Fully resolved deployment view: what the platform materializes for a provider. */
+export interface ResolvedDeploymentIntent {
+	runtime: DeploymentRuntime;
+	language: DeploymentLanguage;
+	replicas: number;
+	hpa: DeploymentHpa;
+	resources: DeploymentResources;
+	cache?: { redis?: { enabled: boolean; url?: string } };
+	network?: { additionalTcpPorts: number[] };
+	buildContext: string;
+}
+
+/**
+ * Runtime-profile defaults. `dedicated` carries no resource profile and
+ * therefore always needs explicit `resources`.
+ */
+export const DEPLOYMENT_PROFILE_DEFAULTS = Object.freeze({
+	runtime: "shared" as DeploymentRuntime,
+	language: "typescript" as DeploymentLanguage,
+	replicas: 1,
+	hpa: Object.freeze({
+		enabled: true,
+		minReplicas: 1,
+		maxReplicas: 1,
+		targetCPUUtilizationPercentage: 70,
+	}) as Readonly<DeploymentHpa>,
+	buildContext: ".",
+	resources: Object.freeze({
+		shared: Object.freeze({ cpu: "25m", memory: "128Mi" }),
+		browser: Object.freeze({ cpu: "200m", memory: "256Mi" }),
+		dedicated: undefined,
+	}) as Readonly<Record<DeploymentRuntime, Readonly<DeploymentResources> | undefined>>,
+});
+
+const BUILD_CONTEXT_CONSTRAINT =
+	'only "." is accepted; external provider images always build from the materialized checkout root';
+
+const hpaSchema = z
+	.object({
+		enabled: z.boolean(),
+		minReplicas: z.number().int().positive().optional(),
+		maxReplicas: z.number().int().positive().optional(),
+		targetCPUUtilizationPercentage: z.number().int().positive().optional(),
+	})
+	.strict();
+
+const resourcesSchema = z.object({ cpu: z.string().min(1), memory: z.string().min(1) }).strict();
+
+const cacheSchema = z
+	.object({
+		redis: z
+			.object({ enabled: z.boolean(), url: z.string().min(1).optional() })
+			.strict()
+			.optional(),
+	})
+	.strict();
+
+const networkSchema = z
+	.object({
+		additionalTcpPorts: z.array(z.number().int().min(1).max(65535)).default([]),
+	})
+	.strict();
+
+const buildContextSchema = z
+	.string()
+	.min(1)
+	.refine((value) => value === ".", { message: BUILD_CONTEXT_CONSTRAINT });
+
+/**
+ * The standalone `deploy.ts` contract (legacy). Mirrors the registry's
+ * `ProviderDeploymentConfigSchema`, including its own defaults — note that a
+ * legacy file without `hpa` resolved to `{ enabled: false }`, not the
+ * profile HPA, so the two default tables are deliberately different.
+ */
+export const legacyDeploymentConfigSchema = z
+	.object({
+		runtime: z.enum(["shared", "dedicated", "browser"]),
+		language: z.enum(["typescript", "python"]),
+		replicas: z.number().int().positive().default(1),
+		hpa: hpaSchema.default({ enabled: false }),
+		resources: resourcesSchema,
+		cache: cacheSchema.optional(),
+		network: networkSchema.optional(),
+		buildContext: buildContextSchema.optional(),
+	})
+	.strict();
+
+/** The authored `deployment` key: every field optional (registry `ProviderDeploymentOverridesSchema`). */
+export const deploymentOverridesSchema = z
+	.object({
+		runtime: z.enum(["shared", "dedicated", "browser"]).optional(),
+		language: z.enum(["typescript", "python"]).optional(),
+		replicas: z.number().int().positive().optional(),
+		hpa: hpaSchema.optional(),
+		resources: resourcesSchema.optional(),
+		cache: cacheSchema.optional(),
+		network: networkSchema.optional(),
+		buildContext: buildContextSchema.optional(),
+	})
+	.strict();
+
+export type DeploymentParse<T> =
+	| { readonly ok: true; readonly value: T }
+	| { readonly ok: false; readonly reason: string };
+
+function formatZodIssues(error: z.ZodError): string {
+	return error.issues
+		.map((issue) => {
+			const path = issue.path.map(String).join(".");
+			return path ? `${path}: ${issue.message}` : issue.message;
+		})
+		.join("; ");
+}
+
+/** Parse a legacy `deploy.ts` default export into the resolved view. */
+export function normalizeLegacyDeployment(
+	value: unknown,
+): DeploymentParse<ResolvedDeploymentIntent> {
+	const parsed = legacyDeploymentConfigSchema.safeParse(value);
+	if (!parsed.success) {
+		return {
+			ok: false,
+			reason: `deploy.ts is not a valid deployment config: ${formatZodIssues(parsed.error)}`,
+		};
+	}
+	const legacy = parsed.data;
+	return {
+		ok: true,
+		value: {
+			runtime: legacy.runtime,
+			language: legacy.language,
+			replicas: legacy.replicas,
+			hpa: legacy.hpa,
+			resources: legacy.resources,
+			...(legacy.cache ? { cache: legacy.cache } : {}),
+			...(legacy.network ? { network: legacy.network } : {}),
+			buildContext: legacy.buildContext ?? DEPLOYMENT_PROFILE_DEFAULTS.buildContext,
+		},
+	};
+}
+
+/** Parse an authored `deployment` key against the strict overrides contract. */
+export function parseDeploymentIntent(
+	value: unknown,
+): DeploymentParse<ProviderDeploymentOverrides> {
+	const parsed = deploymentOverridesSchema.safeParse(value);
+	if (!parsed.success) {
+		return { ok: false, reason: `deployment key is invalid: ${formatZodIssues(parsed.error)}` };
+	}
+	return { ok: true, value: parsed.data };
+}
+
+/**
+ * Resolve an authored key against the runtime profiles, per field;
+ * `resources` and `hpa` resolve as whole objects (never deep-merged).
+ * Throws when the intent cannot resolve (dedicated runtime without
+ * resources, non-default buildContext) — the registry rejects the same.
+ */
+export function resolveDeploymentIntent(
+	intent: ProviderDeploymentOverrides = {},
+): ResolvedDeploymentIntent {
+	const runtime = intent.runtime ?? DEPLOYMENT_PROFILE_DEFAULTS.runtime;
+	const resources = intent.resources ?? DEPLOYMENT_PROFILE_DEFAULTS.resources[runtime];
+	if (!resources) {
+		throw new Error(
+			`resources: runtime "${runtime}" has no profile default; declare explicit resources { cpu, memory }`,
+		);
+	}
+	if (
+		intent.buildContext !== undefined &&
+		intent.buildContext !== DEPLOYMENT_PROFILE_DEFAULTS.buildContext
+	) {
+		throw new Error(`buildContext: ${BUILD_CONTEXT_CONSTRAINT}`);
+	}
+	return {
+		runtime,
+		language: intent.language ?? DEPLOYMENT_PROFILE_DEFAULTS.language,
+		replicas: intent.replicas ?? DEPLOYMENT_PROFILE_DEFAULTS.replicas,
+		hpa: intent.hpa ? { ...intent.hpa } : { ...DEPLOYMENT_PROFILE_DEFAULTS.hpa },
+		resources: { ...resources },
+		...(intent.cache ? { cache: cloneJson(intent.cache) } : {}),
+		...(intent.network
+			? { network: { additionalTcpPorts: [...(intent.network.additionalTcpPorts ?? [])] } }
+			: {}),
+		buildContext: intent.buildContext ?? DEPLOYMENT_PROFILE_DEFAULTS.buildContext,
+	};
+}
+
+/**
+ * Two resolved views describe the same deployment when they are deep-equal
+ * after dropping empty shells (`network: { additionalTcpPorts: [] }`,
+ * `cache: {}`) that carry no intent — the manifests they render are
+ * byte-identical.
+ */
+export function deploymentIntentsEquivalent(
+	left: ResolvedDeploymentIntent,
+	right: ResolvedDeploymentIntent,
+): boolean {
+	return deepEqual(canonicalResolvedDeployment(left), canonicalResolvedDeployment(right));
+}
+
+export function canonicalResolvedDeployment(
+	resolved: ResolvedDeploymentIntent,
+): ResolvedDeploymentIntent {
+	const { cache, network, ...rest } = resolved;
+	const canonical: ResolvedDeploymentIntent = { ...rest };
+	if (cache?.redis !== undefined) canonical.cache = { redis: { ...cache.redis } };
+	if (network !== undefined && network.additionalTcpPorts.length > 0) {
+		canonical.network = { additionalTcpPorts: [...network.additionalTcpPorts] };
+	}
+	return canonical;
+}
+
+/**
+ * The smallest `deployment` key that resolves to `resolved`: profile
+ * defaults are omitted, `hpa`/`resources` are kept whole when they differ
+ * (the resolver never deep-merges them), and empty shells are dropped.
+ * Callers prove the result with
+ * `deploymentIntentsEquivalent(resolveDeploymentIntent(key), resolved)`.
+ */
+export function subtractDeploymentDefaults(
+	resolved: ResolvedDeploymentIntent,
+): ProviderDeploymentOverrides {
+	const intent: ProviderDeploymentOverrides = {};
+	if (resolved.runtime !== DEPLOYMENT_PROFILE_DEFAULTS.runtime) intent.runtime = resolved.runtime;
+	if (resolved.language !== DEPLOYMENT_PROFILE_DEFAULTS.language)
+		intent.language = resolved.language;
+	if (resolved.replicas !== DEPLOYMENT_PROFILE_DEFAULTS.replicas)
+		intent.replicas = resolved.replicas;
+	if (!deepEqual(resolved.hpa, DEPLOYMENT_PROFILE_DEFAULTS.hpa)) intent.hpa = { ...resolved.hpa };
+	const profileResources = DEPLOYMENT_PROFILE_DEFAULTS.resources[resolved.runtime];
+	if (profileResources === undefined || !deepEqual(resolved.resources, profileResources)) {
+		intent.resources = { ...resolved.resources };
+	}
+	if (resolved.cache?.redis !== undefined) intent.cache = { redis: { ...resolved.cache.redis } };
+	if (resolved.network !== undefined && resolved.network.additionalTcpPorts.length > 0) {
+		intent.network = { additionalTcpPorts: [...resolved.network.additionalTcpPorts] };
+	}
+	// buildContext: "." is the only accepted value, so it is never authored.
+	return intent;
+}
+
+/** Authored order for emitted keys: the registry contract's field order. */
+export const DEPLOYMENT_INTENT_FIELD_ORDER: readonly (keyof ProviderDeploymentOverrides)[] = [
+	"runtime",
+	"language",
+	"replicas",
+	"hpa",
+	"resources",
+	"cache",
+	"network",
+	"buildContext",
+];
+
+export interface RedundantDeploymentField {
+	/** Dotted path under `deployment`, e.g. `hpa` or `network.additionalTcpPorts`. */
+	readonly path: string;
+	readonly message: string;
+}
+
+/**
+ * Fields of an authored `deployment` key that restate what the runtime
+ * profile already resolves (ADR-0009 "derived values are not re-stated").
+ * Accepts an unvalidated value because `apifuse check` inspects the loaded
+ * definition, whose key the SDK passes through verbatim.
+ */
+export function redundantDeploymentDefaults(intent: unknown): RedundantDeploymentField[] {
+	if (!isRecord(intent)) return [];
+	const redundant: RedundantDeploymentField[] = [];
+	const flag = (path: string, detail: string): void => {
+		redundant.push({ path, message: `deployment.${path} ${detail}; omit it` });
+	};
+	if (intent.runtime === DEPLOYMENT_PROFILE_DEFAULTS.runtime) {
+		flag("runtime", `restates the profile default ("${DEPLOYMENT_PROFILE_DEFAULTS.runtime}")`);
+	}
+	if (intent.language === DEPLOYMENT_PROFILE_DEFAULTS.language) {
+		flag("language", `restates the profile default ("${DEPLOYMENT_PROFILE_DEFAULTS.language}")`);
+	}
+	if (intent.replicas === DEPLOYMENT_PROFILE_DEFAULTS.replicas) {
+		flag("replicas", `restates the profile default (${DEPLOYMENT_PROFILE_DEFAULTS.replicas})`);
+	}
+	if (deepEqual(intent.hpa, DEPLOYMENT_PROFILE_DEFAULTS.hpa)) {
+		flag("hpa", "restates the profile default (enabled, 1-1 replicas, 70% CPU target)");
+	}
+	const runtime =
+		typeof intent.runtime === "string" && intent.runtime in DEPLOYMENT_PROFILE_DEFAULTS.resources
+			? (intent.runtime as DeploymentRuntime)
+			: DEPLOYMENT_PROFILE_DEFAULTS.runtime;
+	const profileResources = DEPLOYMENT_PROFILE_DEFAULTS.resources[runtime];
+	if (profileResources !== undefined && deepEqual(intent.resources, profileResources)) {
+		flag(
+			"resources",
+			`restates the "${runtime}" profile default (${profileResources.cpu}/${profileResources.memory})`,
+		);
+	}
+	if (intent.buildContext === DEPLOYMENT_PROFILE_DEFAULTS.buildContext) {
+		flag("buildContext", 'restates the only accepted value (".")');
+	}
+	if (isRecord(intent.network)) {
+		const ports = intent.network.additionalTcpPorts;
+		if (ports === undefined || (Array.isArray(ports) && ports.length === 0)) {
+			flag("network", "declares no additional TCP ports (empty shell)");
+		}
+	}
+	if (isRecord(intent.cache) && intent.cache.redis === undefined) {
+		flag("cache", "declares no redis intent (empty shell)");
+	}
+	return redundant;
+}
+
+/** Structural equality for JSON-shaped values, key order insensitive. */
+export function deepEqual(left: unknown, right: unknown): boolean {
+	if (left === right) return true;
+	if (Array.isArray(left) || Array.isArray(right)) {
+		if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+		return left.every((item, index) => deepEqual(item, right[index]));
+	}
+	if (!isRecord(left) || !isRecord(right)) return false;
+	const leftKeys = Object.keys(left).filter((key) => left[key] !== undefined);
+	const rightKeys = Object.keys(right).filter((key) => right[key] !== undefined);
+	if (leftKeys.length !== rightKeys.length) return false;
+	return leftKeys.every((key) => Object.hasOwn(right, key) && deepEqual(left[key], right[key]));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function cloneJson<T>(value: T): T {
+	return JSON.parse(JSON.stringify(value)) as T;
+}