@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/bin/apifuse-pack-types.ts

@@ -18,11 +18,11 @@
 //   3. A Node (not bun) ESM runtime import — node does not tolerate
 //      extensionless relative specifiers, bun does.
 //
-// A deliberate negative control proves the fixture compiler actually fails on
+// Deliberate negative controls prove the fixture compiler actually fails on
 // type errors, so this check cannot rot into a false-positive green.
 
 import { execFileSync, spawnSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { z } from "zod";
@@ -36,6 +36,631 @@ const PACK_RESULT_SCHEMA = z.array(
 const KEEP_TEMP = process.env.APIFUSE__PACK_TYPES__KEEP_TEMP === "1";
 const sdkRoot = process.cwd();
 
+const NEGATIVE_CONTROLS = [
+	{
+		filename: "negative-control-provider-error-name.ts",
+		expectedCode: "TS2322",
+		description: "ProviderError.name remains a string",
+		source: [
+			'import { ProviderError } from "@apifuse/provider-sdk";',
+			"",
+			"// Intentionally wrong: name is a string. If this file compiles, the",
+			"// fixture consumer is not actually type-checking and the guard is void.",
+			'export const mustNotCompile: number = new ProviderError("boom").name;',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-unknown-resolver-vendor.ts",
+		expectedCode: "TS2322",
+		description: "ProviderResolverConfig rejects an unknown vendor",
+		source: [
+			'import type { ProviderResolverConfig } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderResolverConfig = {",
+			'\tvendors: ["unknown-vendor"],',
+			'\tkinds: ["turnstile"],',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-define-provider-resolver-vendor.ts",
+		expectedCode: "TS2322",
+		description: "defineProvider rejects an unknown resolver vendor",
+		source: [
+			'import { defineProvider, z } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile = defineProvider({",
+			'\tid: "invalid-resolver-vendor",',
+			'\tversion: "1.0.0",',
+			'\truntime: "standard",',
+			'\tresolver: { vendors: ["unknown-vendor"], kinds: ["turnstile"] },',
+			'\tmeta: { displayName: "Invalid Resolver Vendor", descriptionKey: "meta.description", category: "test" },',
+			"})({",
+			"\toperations: {",
+			"\t\tprobe: {",
+			'\t\t\triskClass: "read",',
+			"\t\t\tinput: z.object({}),",
+			"\t\t\toutput: z.object({ ok: z.boolean() }),",
+			"\t\t\thandler: async () => ({ ok: true }),",
+			'\t\t\thealthCheckUnsupported: { reason: "type fixture" },',
+			"\t\t},",
+			"\t},",
+			"});",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-unknown-challenge-kind.ts",
+		expectedCode: "TS2820",
+		description: "ProviderChallenge rejects an unknown challenge kind",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "funcaptcha",',
+			'\tsiteKey: "key",',
+			'\tpageUrl: "https://example.com",',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-provider-challenge-kind.ts",
+		expectedCode: "TS2820",
+		description: "ProviderChallengeKind rejects an unknown challenge kind",
+		source: [
+			'import type { ProviderChallengeKind } from "@apifuse/provider-sdk";',
+			"",
+			'export const mustNotCompile: ProviderChallengeKind = "funcaptcha";',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-cookie-solution-token-read.ts",
+		expectedCode: "TS2339",
+		description: "ChallengeSolution requires narrowing before reading token",
+		source: [
+			'import type { ChallengeSolution } from "@apifuse/provider-sdk";',
+			"",
+			"export function mustNotCompile(solution: ChallengeSolution): string {",
+			"\treturn solution.token;",
+			"}",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-cookie-challenge-site-key.ts",
+		expectedCode: "TS2353",
+		description: "cookie-family challenges reject token-family fields",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "cloudflare_interstitial",',
+			'\tpageUrl: "https://example.com",',
+			'\tsiteKey: "not-allowed",',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-aws-waf-site-key-type.ts",
+		expectedCode: "TS2322",
+		description: "aws_waf siteKey must be a string",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "aws_waf",',
+			'\tpageUrl: "https://example.com",',
+			"\tsiteKey: 123,",
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-aws-waf-context-type.ts",
+		expectedCode: "TS2322",
+		description: "aws_waf context must be a string",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "aws_waf",',
+			'\tpageUrl: "https://example.com",',
+			"\tcontext: 123,",
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-aws-waf-unknown-field.ts",
+		expectedCode: "TS2353",
+		description: "aws_waf rejects fields it does not declare",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "aws_waf",',
+			'\tpageUrl: "https://example.com",',
+			"\tunknownField: 1,",
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-recaptcha-v3-action.ts",
+		expectedCode: "TS2322",
+		description: "recaptcha_v3 challenges require action",
+		source: [
+			'import type { ProviderChallenge } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ProviderChallenge = {",
+			'\tkind: "recaptcha_v3",',
+			'\tsiteKey: "key",',
+			'\tpageUrl: "https://example.com",',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-browser-cookie-expires.ts",
+		expectedCode: "TS2322",
+		description: "BrowserCookie.expires remains optional for session cookies",
+		source: [
+			'import type { BrowserCookie } from "@apifuse/provider-sdk";',
+			"",
+			"export function mustNotCompile(cookie: BrowserCookie): number {",
+			"\treturn cookie.expires;",
+			"}",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-resolver-runtime-identity.ts",
+		expectedCode: "TS2353",
+		description: "ResolverRuntimeOptions does not accept caller-synthesized identity",
+		source: [
+			'import type { ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverRuntimeOptions = {",
+			'\tidentity: "caller-controlled",',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-resolver-runtime-adapter-factories.ts",
+		expectedCode: "TS2353",
+		description: "ResolverRuntimeOptions does not accept caller-supplied adapter factories",
+		source: [
+			'import type { ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverRuntimeOptions = {",
+			"\tadapterFactories: {},",
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-resolver-default-user-agent-test-seam.ts",
+		expectedCode: "TS2305",
+		description: "the resolver subpath does not expose its default user-agent test seam",
+		source: [
+			'import { swapResolverDefaultUserAgentForTests } from "@apifuse/provider-sdk/runtime/resolver";',
+			"",
+			"export const mustNotCompile = swapResolverDefaultUserAgentForTests;",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-cache-reset-test-seam.ts",
+		expectedCode: "TS2305",
+		description: "the package root does not expose its cache-reset test seam",
+		source: [
+			'import { resetProviderCacheForTests } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile = resetProviderCacheForTests;",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-resolver-runtime-allowed-hosts.ts",
+		expectedCode: "TS2322",
+		description: "ResolverRuntimeOptions.allowedHosts accepts only host strings",
+		source: [
+			'import type { ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverRuntimeOptions = {",
+			'\tallowedHosts: ["example.com", 42],',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-resolver-signal.ts",
+		expectedCode: "TS2345",
+		description: "ResolverContext.solve accepts only AbortSignal as its optional signal",
+		source: [
+			'import type { ProviderChallenge, ResolverContext } from "@apifuse/provider-sdk";',
+			"",
+			"declare const resolver: ResolverContext;",
+			"declare const challenge: ProviderChallenge;",
+			"resolver.solve(challenge, { aborted: false });",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-proxy-telemetry-vendor.ts",
+		expectedCode: "TS2322",
+		description: "proxy gateway telemetry rejects an unbranded vendor string",
+		source: [
+			'import type { TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"const bad: TelemetryContributor<{}, { vendor: string }> = {",
+			'\tkey: "proxy",',
+			"\ttoLogPayload: () => ({}),",
+			'\ttoHeaderPayload: () => ({ vendor: "free-text" }),',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-header-host.ts",
+		expectedCode: "TS2322",
+		description: "gateway telemetry headers reject an unbranded host string",
+		source: [
+			'import type { TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"const bad: TelemetryContributor<{}, { host: string }> = {",
+			'\tkey: "http",',
+			"\ttoLogPayload: () => ({}),",
+			'\ttoHeaderPayload: () => ({ host: "x.example" }),',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-tenant-vendor.ts",
+		expectedCode: "TS2322",
+		description: "tenant-neutral projections reject vendor identities",
+		source: [
+			'import type { TenantNeutral } from "@apifuse/provider-sdk";',
+			"",
+			'export const bad: TenantNeutral<{ vendorUsed: "smartproxy" }> = { vendorUsed: "smartproxy" };',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-header-any.ts",
+		expectedCode: "TS2322",
+		description: "gateway telemetry projections reject any-valued properties",
+		source: [
+			'import type { GatewayIngestible } from "@apifuse/provider-sdk";',
+			"",
+			'export const bad: GatewayIngestible<{ x: any }> = { x: "free-text" };',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-header-union-array.ts",
+		expectedCode: "TS2322",
+		description: "gateway telemetry projections reject arrays mixing numbers and strings",
+		source: [
+			'import type { TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"const bad: TelemetryContributor<{}, { values: (number | string)[] }> = {",
+			'\tkey: "resolver",',
+			"\ttoLogPayload: () => ({}),",
+			'\ttoHeaderPayload: () => ({ values: [1, "free prose"] }),',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-opaque-identity.ts",
+		expectedCode: "TS2322",
+		description: "tenant opaque array brands are not accepted outside the cache keys property",
+		source: [
+			'import type { TenantNeutral } from "@apifuse/provider-sdk";',
+			"",
+			"type LocalOpaque = string[] & { readonly __tenantOpaqueCacheKeys: true };",
+			"declare const opaque: LocalOpaque;",
+			"export const bad: TenantNeutral<{ identity: LocalOpaque }> = { identity: opaque };",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-meta-vendor.ts",
+		expectedCode: "TS2322",
+		description: "success metadata rejects tenant-visible vendor identity keys",
+		source: [
+			'import { closedEnum, type ClosedEnum, type TenantNeutral } from "@apifuse/provider-sdk";',
+			"",
+			'type Meta = { cached: boolean; detail: { vendorUsed: ClosedEnum<"smartproxy"> } };',
+			'export const bad: TenantNeutral<Meta> = { cached: false, detail: { vendorUsed: closedEnum("smartproxy") } };',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-proxy-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "proxy telemetry contributor satisfies the public contributor contract",
+		source: [
+			'import { closedEnum, type ClosedEnum, type GatewayIngestible, type ProxyTelemetryHeaderPayload, type ProxyTelemetryLogPayload, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"export const proxy: TelemetryContributor<ProxyTelemetryLogPayload, ProxyTelemetryHeaderPayload> = {",
+			'\tkey: "proxy",',
+			'\ttoLogPayload: () => ({ kind: "unresolved", vendors: [] }),',
+			'\ttoHeaderPayload: () => ({ kind: closedEnum("unresolved"), vendors: [] }),',
+			"};",
+			'type Values = { values: ClosedEnum<"a" | "b">[] };',
+			'export const values: GatewayIngestible<Values> = { values: [closedEnum("a"), closedEnum("b")] };',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-resolver-telemetry-description.ts",
+		expectedCode: "TS2353",
+		description: "resolver gateway telemetry rejects vendor error descriptions",
+		source: [
+			'import type { ResolverTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverTelemetryHeaderPayload = {",
+			"\tattempts: 0,",
+			"\tfailovers: 0,",
+			"\tvendorChain: [],",
+			"\tpollCount: 0,",
+			'\tvendorErrorDescription: "free text must stay log-only",',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-resolver-telemetry-phase.ts",
+		expectedCode: "TS2322",
+		description: "resolver gateway telemetry rejects phases outside its closed vocabulary",
+		source: [
+			'import { closedEnum, type ResolverTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverTelemetryHeaderPayload = {",
+			"\tattempts: 1,",
+			"\tfailovers: 0,",
+			'\tvendorChain: [closedEnum("hypersolutions")],',
+			"\tpollCount: 0,",
+			'\tattemptSamples: [{ v: closedEnum("hypersolutions"), p: closedEnum("solve_exchange"), o: closedEnum("error"), ms: 1 }],',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-resolver-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "resolver telemetry contributor satisfies the gateway-ingestible contract",
+		source: [
+			'import { closedEnum, ResolverTelemetryCollector, type GatewayIngestible, type ResolverTelemetryHeaderPayload, type ResolverTelemetryLogPayload, type ResolverTelemetryPhase, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"export const resolver: TelemetryContributor<ResolverTelemetryLogPayload, ResolverTelemetryHeaderPayload> = new ResolverTelemetryCollector();",
+			'const hyperPhases: ResolverTelemetryPhase[] = ["measure_ip", "fetch_script", "generate_payload", "post_payload"];',
+			'export const hyperPhaseHeader: ResolverTelemetryHeaderPayload = { attempts: 1, failovers: 0, vendorChain: [closedEnum("hypersolutions")], pollCount: 0, attemptSamples: hyperPhases.map((phase) => ({ v: closedEnum("hypersolutions"), p: closedEnum(phase), o: closedEnum("ok"), ms: 1 })) };',
+			"declare const header: ResolverTelemetryHeaderPayload;",
+			"export const ingestible: GatewayIngestible<ResolverTelemetryHeaderPayload> = header;",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-native-telemetry-description.ts",
+		expectedCode: "TS2322",
+		description: "native gateway telemetry rejects free-string diagnostic fields",
+		source: [
+			'import type { GatewayIngestible, NativeTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"type UnsafeHeader = NativeTelemetryHeaderPayload & { vendorErrorMessage: string };",
+			"declare const header: NativeTelemetryHeaderPayload;",
+			'export const mustNotCompile: GatewayIngestible<UnsafeHeader> = { ...header, vendorErrorMessage: "free text stays log-only" };',
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-native-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "native telemetry contributor satisfies the gateway-ingestible contract",
+		source: [
+			'import { NativeTelemetryCollector, type GatewayIngestible, type NativeTelemetryHeaderPayload, type NativeTelemetryLogPayload, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			"export const native: TelemetryContributor<NativeTelemetryLogPayload, NativeTelemetryHeaderPayload> = new NativeTelemetryCollector();",
+			"declare const header: NativeTelemetryHeaderPayload;",
+			"export const ingestible: GatewayIngestible<NativeTelemetryHeaderPayload> = header;",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-http-telemetry-free-text.ts",
+		expectedCode: "TS2322",
+		description: "HTTP gateway telemetry rejects a free-string diagnostic field",
+		source: [
+			'import type { HttpTelemetryHeaderPayload, GatewayIngestible } from "@apifuse/provider-sdk";',
+			"type UnsafeHttpHeader = HttpTelemetryHeaderPayload & { message: string };",
+			"declare const header: HttpTelemetryHeaderPayload;",
+			'export const mustNotCompile: GatewayIngestible<UnsafeHttpHeader> = { ...header, message: "upstream free text" };',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-http-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "HTTP contributor satisfies the gateway and tenant projection contracts",
+		source: [
+			'import { HttpTelemetryCollector, type HttpTelemetryHeaderPayload, type HttpTelemetryLogPayload, type HttpTelemetryRetryPayload, type GatewayIngestible, type TenantNeutral, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			'import { HttpTelemetryCollector as ServerHttpCollector } from "@apifuse/provider-sdk/server";',
+			"export const http: TelemetryContributor<HttpTelemetryLogPayload, HttpTelemetryHeaderPayload> = new HttpTelemetryCollector();",
+			"declare const header: HttpTelemetryHeaderPayload;",
+			"export const ingestible: GatewayIngestible<HttpTelemetryHeaderPayload> = header;",
+			"export const retry: TenantNeutral<HttpTelemetryRetryPayload> | undefined = new ServerHttpCollector().toTenantRetryPayload();",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-stealth-telemetry-diagnostics.ts",
+		expectedCode: "TS2322",
+		description: "stealth gateway telemetry rejects a free-string header field",
+		source: [
+			'import { type GatewayIngestible, type StealthTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"type UnsafeHeader = StealthTelemetryHeaderPayload & { diagnostics: string };",
+			"declare const unsafeHeader: UnsafeHeader;",
+			"export const mustNotCompile: GatewayIngestible<UnsafeHeader> = unsafeHeader;",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-stealth-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "stealth telemetry contributor satisfies the gateway-ingestible contract",
+		source: [
+			'import { StealthTelemetryCollector, type GatewayIngestible, type StealthTelemetryHeaderPayload, type StealthTelemetryLogPayload, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"export const stealth: TelemetryContributor<StealthTelemetryLogPayload, StealthTelemetryHeaderPayload> = new StealthTelemetryCollector();",
+			"declare const header: StealthTelemetryHeaderPayload;",
+			"export const ingestible: GatewayIngestible<StealthTelemetryHeaderPayload> = header;",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-ocr-telemetry-free-text.ts",
+		expectedCode: "TS2322",
+		description: "ocr gateway telemetry rejects a free-string field",
+		source: [
+			'import type { GatewayIngestible, OcrTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"type Unsafe = OcrTelemetryHeaderPayload & { message: string };",
+			"declare const value: Unsafe;",
+			"export const bad: GatewayIngestible<Unsafe> = value;",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-ocr-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "ocr telemetry contributor satisfies the gateway-ingestible contract",
+		source: [
+			'import { OcrTelemetryCollector, type TelemetryContributor, type OcrTelemetryLogPayload, type OcrTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"export const ocr: TelemetryContributor<OcrTelemetryLogPayload, OcrTelemetryHeaderPayload> = new OcrTelemetryCollector();",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-stt-telemetry-free-text.ts",
+		expectedCode: "TS2322",
+		description: "stt gateway telemetry rejects a free-string field",
+		source: [
+			'import type { GatewayIngestible, SttTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"type Unsafe = SttTelemetryHeaderPayload & { message: string };",
+			"declare const value: Unsafe;",
+			"export const bad: GatewayIngestible<Unsafe> = value;",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-stt-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "stt telemetry contributor satisfies the gateway-ingestible contract",
+		source: [
+			'import { SttTelemetryCollector, type TelemetryContributor, type SttTelemetryLogPayload, type SttTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"export const stt: TelemetryContributor<SttTelemetryLogPayload, SttTelemetryHeaderPayload> = new SttTelemetryCollector();",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-browser-telemetry-free-text.ts",
+		expectedCode: "TS2322",
+		description: "browser gateway telemetry rejects a free-string field",
+		source: [
+			'import type { BrowserTelemetryHeaderPayload, GatewayIngestible } from "@apifuse/provider-sdk";',
+			"declare const header: BrowserTelemetryHeaderPayload;",
+			"type Unsafe = BrowserTelemetryHeaderPayload & { message: string };",
+			'export const bad: GatewayIngestible<Unsafe> = { ...header, message: "free text" };',
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-browser-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "browser telemetry contributor satisfies the gateway-ingestible contract",
+		source: [
+			'import { BrowserTelemetryCollector, type BrowserTelemetryHeaderPayload, type BrowserTelemetryLogPayload, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			"export const browser: TelemetryContributor<BrowserTelemetryLogPayload, BrowserTelemetryHeaderPayload> = new BrowserTelemetryCollector();",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-cache-telemetry-free-text.ts",
+		expectedCode: "TS2322",
+		description: "cache gateway telemetry rejects raw cache-key samples",
+		source: [
+			'import type { TelemetryContributor } from "@apifuse/provider-sdk";',
+			"const bad: TelemetryContributor<{}, { key: string }> = {",
+			'\tkey: "cache",',
+			"\ttoLogPayload: () => ({}),",
+			'\ttoHeaderPayload: () => ({ key: "raw" }),',
+			"};",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-cache-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "cache telemetry contributor satisfies the public contributor contract",
+		source: [
+			'import { CacheTelemetryCollector, type TelemetryContributor, type CacheTelemetryHeaderPayload, type CacheTelemetryLogPayload } from "@apifuse/provider-sdk";',
+			"export const cache: TelemetryContributor<CacheTelemetryLogPayload, CacheTelemetryHeaderPayload> = new CacheTelemetryCollector();",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-state-telemetry-free-text.ts",
+		expectedCode: "TS2322",
+		description: "state gateway telemetry rejects raw state-key samples",
+		source: [
+			'import type { TelemetryContributor } from "@apifuse/provider-sdk";',
+			"const bad: TelemetryContributor<{}, { key: string }> = {",
+			'\tkey: "state",',
+			"\ttoLogPayload: () => ({}),",
+			'\ttoHeaderPayload: () => ({ key: "raw" }),',
+			"};",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-state-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "state telemetry contributor satisfies the public contributor contract",
+		source: [
+			'import { StateTelemetryCollector, type TelemetryContributor, type StateTelemetryHeaderPayload, type StateTelemetryLogPayload } from "@apifuse/provider-sdk";',
+			"export const state: TelemetryContributor<StateTelemetryLogPayload, StateTelemetryHeaderPayload> = new StateTelemetryCollector();",
+		].join("\n"),
+	},
+] as const;
+
+assertTelemetryContributorControls();
+
+function assertTelemetryContributorControls(): void {
+	const requestTelemetry = readFileSync(join(sdkRoot, "src/runtime/request-telemetry.ts"), "utf8");
+	const priorityMatch = requestTelemetry.match(
+		/const HEADER_PRIORITY = \[([\s\S]*?)\] as const satisfies/,
+	);
+	if (!priorityMatch) throw new Error("Could not read request telemetry header priority list");
+
+	const priority = [...priorityMatch[1].matchAll(/"([a-z]+)"/g)].map((match) => match[1]);
+	const shipped = priority.filter((name) =>
+		existsSync(join(sdkRoot, "src/runtime", `${name}-telemetry.ts`)),
+	);
+	const missing: string[] = [];
+	for (const name of shipped) {
+		const hasPositive = NEGATIVE_CONTROLS.some(
+			({ filename }) => filename === `positive-control-${name}-telemetry-contributor.ts`,
+		);
+		const hasNegative = NEGATIVE_CONTROLS.some(({ filename }) =>
+			filename.startsWith(`negative-control-${name}-telemetry-`),
+		);
+		if (!hasNegative || !hasPositive) {
+			missing.push(
+				`${name} (${hasNegative ? "negative" : "missing negative"}, ${hasPositive ? "positive" : "missing positive"})`,
+			);
+		}
+	}
+	if (missing.length > 0) {
+		throw new Error(`Missing telemetry contributor pack controls: ${missing.join(", ")}`);
+	}
+}
+
 const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-types-"));
 const packDir = join(tempRoot, "pack");
 const consumerDir = join(tempRoot, "consumer");
@@ -123,12 +748,16 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 	writeFileSync(
 		join(consumerDir, "consumer.ts"),
 		[
-			'import { ProviderError, SessionExpiredError, z } from "@apifuse/provider-sdk";',
+			'import { defineProvider, ProviderError, resolveProxy, SessionExpiredError, z } from "@apifuse/provider-sdk";',
+			'import { invalidateResolverSolution } from "@apifuse/provider-sdk/runtime/resolver";',
+			'import type { BrowserCookie, ChallengeSolution, NativeContext, NativeNetworkClient, NativeNetworkConnection, NativeProviderConfig, NativeTcpEgressGrant, ProviderChallenge, ProviderContext, ProviderFileRef, ProviderFilesContext, ProviderResolvedFile, ProviderResolverConfig, ResolverContext, ResolverRuntimeOptions } from "@apifuse/provider-sdk";',
+			'import type { ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyVendorName, RequestOptions, ResolvedProxyConfig } from "@apifuse/provider-sdk";',
 			'import { defineCredentialsAuth } from "@apifuse/provider-sdk/provider";',
+			'import type { NativeNetworkClient as ProviderEntryNativeNetworkClient, ProviderFilesContext as ProviderEntryFilesContext } from "@apifuse/provider-sdk/provider";',
 			'import { extractProviderContract } from "@apifuse/provider-sdk/contract";',
 			'import { AUTH_TURN_SCHEMA } from "@apifuse/provider-sdk/auth-turn";',
 			'import { serve } from "@apifuse/provider-sdk/server";',
-			'import { runStandardTests } from "@apifuse/provider-sdk/testing";',
+			'import { resetProviderCacheForTests, runStandardTests } from "@apifuse/provider-sdk/testing";',
 			"",
 			"// ProviderError must keep its inherited Error members under nodenext.",
 			"// When dist d.ts imports fail to resolve, the class type degrades and",
@@ -143,6 +772,44 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 			"// Re-exported zod must keep .refine() callback parameter inference.",
 			"const refined = z.object({ shopId: z.string() }).refine((value) => value.shopId.length > 0);",
 			'const refinedString = z.string().refine((value) => value.startsWith("tabelog:"));',
+			'const proxyOptions: ProxyResolutionOptions = { proxyPolicy: { mode: "disabled" } };',
+			'const proxyProtocol: ProxyProtocol = "http";',
+			"const proxyResult: Promise<ResolvedProxyConfig> = resolveProxy(proxyOptions);",
+			'const proxySource: ProxyResolutionSource = "smartproxy-allocator";',
+			'const proxyVendor: ProxyVendorName = "smartproxy";',
+			'const requestFile: ProviderFileRef = { type: "request_file", id: "photo", filename: "photo.jpg", mime_type: "image/jpeg", size: 4 };',
+			'const resolvedFile: ProviderResolvedFile = { type: "request_file", id: requestFile.id, filename: requestFile.filename, size: requestFile.size, sha256: requestFile.sha256, mimeType: requestFile.mime_type, arrayBuffer: async () => new ArrayBuffer(0), bytes: async () => new Uint8Array(), stream: () => new ReadableStream<Uint8Array>() };',
+			"const files: ProviderFilesContext = { has: () => true, resolve: async () => resolvedFile };",
+			"const providerEntryFiles: ProviderEntryFilesContext = files;",
+			"const connection: NativeNetworkConnection = { read: async () => null, write: async () => {}, close: async () => {} };",
+			"const network: NativeNetworkClient = { connectTcp: async () => connection, connectTls: async () => connection, grantTcpEgress: () => ({ revoke() {} }) };",
+			"const providerEntryNetwork: ProviderEntryNativeNetworkClient = network;",
+			"const nativeContext: NativeContext = { network };",
+			'const grant: NativeTcpEgressGrant = network.grantTcpEgress({ sourceHost: "booking-loco.kakao.com", sourcePort: 443, host: "loco.kakao.com", port: 5228, tls: "disabled" });',
+			'const nativeConfig: NativeProviderConfig = { network: { tcp: [{ host: "booking-loco.kakao.com", ports: [443], tls: "required" }] } };',
+			"const providerContext = undefined as unknown as ProviderContext;",
+			"const optionalFiles: ProviderFilesContext | undefined = providerContext.files;",
+			"const native: NativeContext = providerContext.native;",
+			"export const providerResolver: ResolverContext = providerContext.resolver;",
+			'export const resolverRuntimeOptions: ResolverRuntimeOptions = { allowedHosts: ["example.com"], cache: providerContext.cache };',
+			"",
+			'export const turnstileChallenge: ProviderChallenge = { kind: "turnstile", siteKey: "key", pageUrl: "https://example.com" };',
+			"export const abortableResolverSolve = providerResolver.solve(turnstileChallenge, new AbortController().signal);",
+			'export const recaptchaV2Challenge: ProviderChallenge = { kind: "recaptcha_v2", siteKey: "key", pageUrl: "https://example.com" };',
+			'export const recaptchaV3Challenge: ProviderChallenge = { kind: "recaptcha_v3", siteKey: "key", pageUrl: "https://example.com", action: "login" };',
+			'export const hcaptchaChallenge: ProviderChallenge = { kind: "hcaptcha", siteKey: "key", pageUrl: "https://example.com" };',
+			'export const cloudflareInterstitialChallenge: ProviderChallenge = { kind: "cloudflare_interstitial", pageUrl: "https://example.com", blockedHtml: "<html></html>" };',
+			'export const awsWafChallenge: ProviderChallenge = { kind: "aws_waf", pageUrl: "https://example.com", captchaScript: "script" };',
+			'export const tokenSolution: ChallengeSolution = { form: "token", token: "solved-token" };',
+			'export const cookieSolution: ChallengeSolution = { form: "cookies", cookies: { cf_clearance: "clearance" }, userAgent: "fixture-agent" };',
+			"export const invalidation = invalidateResolverSolution(providerContext.resolver, awsWafChallenge, cookieSolution);",
+			'export const resolverConfig: ProviderResolverConfig = { vendors: ["browser", "capsolver"], kinds: ["cloudflare_interstitial", "turnstile"] };',
+			'export const resolverProvider = defineProvider({ id: "pack-types-resolver", version: "1.0.0", runtime: "standard", resolver: resolverConfig, meta: { displayName: "Pack Types Resolver", descriptionKey: "meta.description", category: "test" } })({ operations: { probe: { riskClass: "read", input: z.object({}), output: z.object({ ok: z.boolean() }), handler: async () => ({ ok: true }), healthCheckUnsupported: { reason: "type fixture" } } } });',
+			"export const resolverContext: ResolverContext = { solve: async () => tokenSolution };",
+			'export const browserCookie: BrowserCookie = { name: "persistent-id", value: "persistent-token", domain: "example.com", path: "/", expires: 1786698176, httpOnly: true, secure: true };',
+			'const browserPage = undefined as unknown as Awaited<ReturnType<ProviderContext["browser"]["newPage"]>>;',
+			"export const browserCookies: Promise<readonly BrowserCookie[]> = browserPage.cookies();",
+			'const queryCredentialOptions: RequestOptions = { sensitiveParams: { serviceKey: "type-test-key" } };',
 			"",
 			"export const witnesses = {",
 			"	inheritedName,",
@@ -152,27 +819,39 @@ function setUpFixtureConsumer(consumerDir: string, tarballPath: string): void {
 			"	sessionExpired,",
 			"	refined,",
 			"	refinedString,",
+			"	proxyResult,",
+			"	proxyProtocol,",
+			"	proxySource,",
+			"	proxyVendor,",
+			"	requestFile,",
+			"	resolvedFile,",
+			"	files,",
+			"	providerEntryFiles,",
+			"	connection,",
+			"	network,",
+			"	providerEntryNetwork,",
+			"	nativeContext,",
+			"	grant,",
+			"	nativeConfig,",
+			"	optionalFiles,",
+			"	native,",
+			"	browserCookie,",
+			"	browserCookies,",
+			"	queryCredentialOptions,",
 			"	defineCredentialsAuth,",
 			"	extractProviderContract,",
 			"	AUTH_TURN_SCHEMA,",
 			"	serve,",
+			"	resetProviderCacheForTests,",
 			"	runStandardTests,",
 			"};",
 			"",
 		].join("\n"),
 	);
 
-	writeFileSync(
-		join(consumerDir, "negative-control.ts"),
-		[
-			'import { ProviderError } from "@apifuse/provider-sdk";',
-			"",
-			"// Intentionally wrong: name is a string. If this file compiles, the",
-			"// fixture consumer is not actually type-checking and the guard is void.",
-			'export const mustNotCompile: number = new ProviderError("boom").name;',
-			"",
-		].join("\n"),
-	);
+	for (const negativeControl of NEGATIVE_CONTROLS) {
+		writeFileSync(join(consumerDir, negativeControl.filename), negativeControl.source);
+	}
 }
 
 function compileFixtureConsumer(consumerDir: string): void {
@@ -184,30 +863,49 @@ function compileFixtureConsumer(consumerDir: string): void {
 }
 
 function assertNegativeControlFails(consumerDir: string): void {
-	const result = spawnSync(
-		"bun",
-		[
-			join(consumerDir, "node_modules", ".bin", "tsc"),
-			"--target",
-			"ES2022",
-			"--module",
-			"nodenext",
-			"--moduleResolution",
-			"nodenext",
-			"--strict",
-			"--noEmit",
-			"negative-control.ts",
-		],
-		{ cwd: consumerDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
-	);
-	if (result.status === 0) {
-		throw new Error(
-			"Negative control compiled cleanly: the fixture consumer is not detecting type errors, so the nodenext guard proves nothing.",
+	for (const negativeControl of NEGATIVE_CONTROLS) {
+		const result = spawnSync(
+			"bun",
+			[
+				join(consumerDir, "node_modules", ".bin", "tsc"),
+				"--target",
+				"ES2022",
+				"--module",
+				"nodenext",
+				"--moduleResolution",
+				"nodenext",
+				"--strict",
+				"--noEmit",
+				negativeControl.filename,
+			],
+			{ cwd: consumerDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
 		);
-	}
-	if (!`${result.stdout}\n${result.stderr}`.includes("TS2322")) {
-		throw new Error(
-			`Negative control failed for an unexpected reason (wanted TS2322):\n${result.stdout}\n${result.stderr}`,
+		if (negativeControl.expectedCode === "") {
+			if (result.status !== 0) {
+				throw new Error(
+					`Positive control "${negativeControl.description}" failed to compile:\n${result.stdout}\n${result.stderr}`,
+				);
+			}
+			console.log(`Positive control accepted: ${negativeControl.description}`);
+			continue;
+		}
+		if (result.status === 0) {
+			throw new Error(
+				'Negative control "' +
+					negativeControl.description +
+					'" (' +
+					negativeControl.filename +
+					") compiled cleanly: the fixture consumer is not detecting its error, so the guard proves nothing.",
+			);
+		}
+		const output = `${result.stdout}\n${result.stderr}`;
+		if (!output.includes(negativeControl.expectedCode)) {
+			throw new Error(
+				`Negative control "${negativeControl.description}" (${negativeControl.filename}) failed for an unexpected reason (wanted ${negativeControl.expectedCode}):\n${output}`,
+			);
+		}
+		console.log(
+			`Negative control rejected (${negativeControl.expectedCode}): ${negativeControl.description}`,
 		);
 	}
 }