@oh-my-pi/pi-coding-agent 16.0.5 → 16.0.6

package/src/config/models-config-schema.ts

@@ -1,73 +1,72 @@
-import { z } from "zod/v4";
+import { type } from "arktype";
 
-const OpenRouterRoutingSchema = z.object({
-	only: z.array(z.string()).optional(),
-	order: z.array(z.string()).optional(),
+const OpenRouterRoutingSchema = type({
+	"only?": "string[]",
+	"order?": "string[]",
 });
 
-const VercelGatewayRoutingSchema = z.object({
-	only: z.array(z.string()).optional(),
-	order: z.array(z.string()).optional(),
+const VercelGatewayRoutingSchema = type({
+	"only?": "string[]",
+	"order?": "string[]",
 });
 
-const ReasoningEffortMapSchema = z.object({
-	minimal: z.string().optional(),
-	low: z.string().optional(),
-	medium: z.string().optional(),
-	high: z.string().optional(),
-	xhigh: z.string().optional(),
+const ReasoningEffortMapSchema = type({
+	"minimal?": "string",
+	"low?": "string",
+	"medium?": "string",
+	"high?": "string",
+	"xhigh?": "string",
 });
 
-const OpenAICompatFieldsSchema = z.object({
-	supportsStore: z.boolean().optional(),
-	supportsDeveloperRole: z.boolean().optional(),
-	supportsMultipleSystemMessages: z.boolean().optional(),
-	supportsReasoningEffort: z.boolean().optional(),
-	reasoningEffortMap: ReasoningEffortMapSchema.optional(),
-	maxTokensField: z.enum(["max_completion_tokens", "max_tokens"]).optional(),
-	supportsUsageInStreaming: z.boolean().optional(),
-	requiresToolResultName: z.boolean().optional(),
-	requiresMistralToolIds: z.boolean().optional(),
-	requiresAssistantAfterToolResult: z.boolean().optional(),
-	requiresThinkingAsText: z.boolean().optional(),
-	reasoningContentField: z.enum(["reasoning_content", "reasoning", "reasoning_text"]).optional(),
-	requiresReasoningContentForToolCalls: z.boolean().optional(),
-	allowsSyntheticReasoningContentForToolCalls: z.boolean().optional(),
-	requiresAssistantContentForToolCalls: z.boolean().optional(),
-	supportsToolChoice: z.boolean().optional(),
-	supportsForcedToolChoice: z.boolean().optional(),
-	disableReasoningOnForcedToolChoice: z.boolean().optional(),
-	disableReasoningOnToolChoice: z.boolean().optional(),
-	thinkingFormat: z.enum(["openai", "openrouter", "zai", "qwen", "qwen-chat-template"]).optional(),
-	openRouterRouting: OpenRouterRoutingSchema.optional(),
-	vercelGatewayRouting: VercelGatewayRoutingSchema.optional(),
-	extraBody: z.record(z.string(), z.unknown()).optional(),
-	cacheControlFormat: z.enum(["anthropic"]).optional(),
-	supportsStrictMode: z.boolean().optional(),
-	toolStrictMode: z.enum(["all_strict", "none"]).optional(),
-	streamIdleTimeoutMs: z.number().nonnegative().optional(),
-	supportsLongPromptCacheRetention: z.boolean().optional(),
-	supportsReasoningParams: z.boolean().optional(),
-	alwaysSendMaxTokens: z.boolean().optional(),
-	strictResponsesPairing: z.boolean().optional(),
+const OpenAICompatFields = {
+	"supportsStore?": "boolean",
+	"supportsDeveloperRole?": "boolean",
+	"supportsMultipleSystemMessages?": "boolean",
+	"supportsReasoningEffort?": "boolean",
+	"reasoningEffortMap?": ReasoningEffortMapSchema,
+	"maxTokensField?": '"max_completion_tokens" | "max_tokens"',
+	"supportsUsageInStreaming?": "boolean",
+	"requiresToolResultName?": "boolean",
+	"requiresMistralToolIds?": "boolean",
+	"requiresAssistantAfterToolResult?": "boolean",
+	"requiresThinkingAsText?": "boolean",
+	"reasoningContentField?": '"reasoning_content" | "reasoning" | "reasoning_text"',
+	"requiresReasoningContentForToolCalls?": "boolean",
+	"allowsSyntheticReasoningContentForToolCalls?": "boolean",
+	"requiresAssistantContentForToolCalls?": "boolean",
+	"supportsToolChoice?": "boolean",
+	"supportsForcedToolChoice?": "boolean",
+	"disableReasoningOnForcedToolChoice?": "boolean",
+	"disableReasoningOnToolChoice?": "boolean",
+	"thinkingFormat?": '"openai" | "openrouter" | "zai" | "qwen" | "qwen-chat-template"',
+	"openRouterRouting?": OpenRouterRoutingSchema,
+	"vercelGatewayRouting?": VercelGatewayRoutingSchema,
+	"extraBody?": { "[string]": "unknown" },
+	"cacheControlFormat?": '"anthropic"',
+	"supportsStrictMode?": "boolean",
+	"toolStrictMode?": '"all_strict" | "none"',
+	"streamIdleTimeoutMs?": "number >= 0",
+	"supportsLongPromptCacheRetention?": "boolean",
+	"supportsReasoningParams?": "boolean",
+	"alwaysSendMaxTokens?": "boolean",
+	"strictResponsesPairing?": "boolean",
 	// anthropic-messages compat flags (same `compat` slot, per-api interpretation)
-	requiresToolResultId: z.boolean().optional(),
-	replayUnsignedThinking: z.boolean().optional(),
-});
+	"requiresToolResultId?": "boolean",
+	"replayUnsignedThinking?": "boolean",
+} as const;
+
+const OpenAICompatFieldsSchema = type(OpenAICompatFields);
 
-export const OpenAICompatSchema = OpenAICompatFieldsSchema.extend({
-	whenThinking: OpenAICompatFieldsSchema.optional(),
+export const OpenAICompatSchema = type({
+	...OpenAICompatFields,
+	"whenThinking?": OpenAICompatFieldsSchema,
 });
 
-const EffortSchema = z.enum(["minimal", "low", "medium", "high", "xhigh"]);
+const EffortSchema = type('"minimal" | "low" | "medium" | "high" | "xhigh"');
 
-const ThinkingControlModeSchema = z.enum([
-	"effort",
-	"budget",
-	"google-level",
-	"anthropic-adaptive",
-	"anthropic-budget-effort",
-]);
+const ThinkingControlModeSchema = type(
+	'"effort" | "budget" | "google-level" | "anthropic-adaptive" | "anthropic-budget-effort"',
+);
 
 const EFFORT_ORDER = ["minimal", "low", "medium", "high", "xhigh"] as const;
 
@@ -77,137 +76,141 @@ const EFFORT_ORDER = ["minimal", "low", "medium", "high", "xhigh"] as const;
  * `ThinkingConfig` (ordered `efforts`, never empty). Precedence mirrors the
  * old runtime: explicit `levels` beat the min..max range; `efforts` beats both.
  */
-const ModelThinkingSchema = z
-	.object({
-		mode: ThinkingControlModeSchema,
-		efforts: z.array(EffortSchema).min(1).optional(),
-		defaultLevel: EffortSchema.optional(),
-		effortMap: ReasoningEffortMapSchema.optional(),
-		supportsDisplay: z.boolean().optional(),
-		// Legacy range vocabulary (pre-efforts configs).
-		minLevel: EffortSchema.optional(),
-		maxLevel: EffortSchema.optional(),
-		levels: z.array(EffortSchema).min(1).optional(),
-	})
-	.refine(
-		value =>
+const ModelThinkingSchema = type({
+	mode: ThinkingControlModeSchema,
+	"efforts?": EffortSchema.array(),
+	"defaultLevel?": EffortSchema,
+	"effortMap?": ReasoningEffortMapSchema,
+	"supportsDisplay?": "boolean",
+	// Legacy range vocabulary (pre-efforts configs).
+	"minLevel?": EffortSchema,
+	"maxLevel?": EffortSchema,
+	"levels?": EffortSchema.array(),
+})
+	.narrow(
+		(value, ctx) =>
 			value.efforts !== undefined ||
 			value.levels !== undefined ||
-			(value.minLevel !== undefined && value.maxLevel !== undefined),
-		{
-			message: "thinking requires `efforts` (or legacy `levels`/`minLevel`+`maxLevel`)",
-		},
+			(value.minLevel !== undefined && value.maxLevel !== undefined) ||
+			ctx.mustBe("thinking with `efforts` (or legacy `levels`/`minLevel`+`maxLevel`)"),
 	)
-	.transform(({ efforts, levels, minLevel, maxLevel, mode, defaultLevel, effortMap, supportsDisplay }) => {
-		let resolved = efforts ?? levels;
+	.pipe((value: any) => {
+		let resolved = value.efforts ?? value.levels;
 		if (!resolved) {
-			const minIndex = EFFORT_ORDER.indexOf(minLevel!);
-			const maxIndex = EFFORT_ORDER.indexOf(maxLevel!);
+			const minIndex = EFFORT_ORDER.indexOf(value.minLevel!);
+			const maxIndex = EFFORT_ORDER.indexOf(value.maxLevel!);
 			resolved = EFFORT_ORDER.slice(minIndex, Math.max(minIndex, maxIndex) + 1);
 		}
 		return {
-			mode,
+			mode: value.mode,
 			efforts: resolved,
-			...(defaultLevel !== undefined && { defaultLevel }),
-			...(effortMap !== undefined && { effortMap }),
-			...(supportsDisplay !== undefined && { supportsDisplay }),
+			...(value.defaultLevel !== undefined && { defaultLevel: value.defaultLevel }),
+			...(value.effortMap !== undefined && { effortMap: value.effortMap }),
+			...(value.supportsDisplay !== undefined && { supportsDisplay: value.supportsDisplay }),
 		};
 	});
 
-const ModelDefinitionSchema = z.object({
-	id: z.string().min(1),
-	name: z.string().min(1).optional(),
-	api: z
-		.enum([
-			"openai-completions",
-			"openai-responses",
-			"openai-codex-responses",
-			"azure-openai-responses",
-			"anthropic-messages",
-			"google-generative-ai",
-			"google-gemini-cli",
-			"google-vertex",
-		])
-		.optional(),
-	baseUrl: z.string().min(1).optional(),
-	reasoning: z.boolean().optional(),
-	thinking: ModelThinkingSchema.optional(),
-	input: z.array(z.enum(["text", "image"])).optional(),
-	supportsTools: z.boolean().optional(),
-	cost: z
-		.object({
-			input: z.number(),
-			output: z.number(),
-			cacheRead: z.number(),
-			cacheWrite: z.number(),
-		})
-		.optional(),
-	premiumMultiplier: z.number().optional(),
-	contextWindow: z.number().optional(),
-	maxTokens: z.number().optional(),
-	omitMaxOutputTokens: z.boolean().optional(),
-	headers: z.record(z.string(), z.string()).optional(),
-	compat: OpenAICompatSchema.optional(),
-	contextPromotionTarget: z.string().min(1).optional(),
+const ModelDefinitionSchema = type({
+	id: "string",
+	"name?": "string",
+	"api?":
+		'"openai-completions" | "openai-responses" | "openai-codex-responses" | "azure-openai-responses" | "anthropic-messages" | "google-generative-ai" | "google-gemini-cli" | "google-vertex"',
+	"baseUrl?": "string",
+	"reasoning?": "boolean",
+	"thinking?": ModelThinkingSchema,
+	"input?": '("text" | "image")[]',
+	"supportsTools?": "boolean",
+	"cost?": {
+		input: "number",
+		output: "number",
+		cacheRead: "number",
+		cacheWrite: "number",
+	},
+	"premiumMultiplier?": "number",
+	"contextWindow?": "number",
+	"maxTokens?": "number",
+	"omitMaxOutputTokens?": "boolean",
+	"headers?": { "[string]": "string" },
+	"compat?": OpenAICompatSchema,
+	"contextPromotionTarget?": "string",
+}).narrow((value, ctx) => {
+	// Enforce id non-empty
+	if (typeof value.id === "string" && value.id.length === 0) {
+		return ctx.mustBe("id a non-empty string");
+	}
+	if (value.name !== undefined && typeof value.name === "string" && value.name.length === 0) {
+		return ctx.mustBe("name a non-empty string");
+	}
+	if (value.baseUrl !== undefined && typeof value.baseUrl === "string" && value.baseUrl.length === 0) {
+		return ctx.mustBe("baseUrl a non-empty string");
+	}
+	if (
+		value.contextPromotionTarget !== undefined &&
+		typeof value.contextPromotionTarget === "string" &&
+		value.contextPromotionTarget.length === 0
+	) {
+		return ctx.mustBe("contextPromotionTarget a non-empty string");
+	}
+	return true;
 });
 
-export const ModelOverrideSchema = z.object({
-	name: z.string().min(1).optional(),
-	reasoning: z.boolean().optional(),
-	thinking: ModelThinkingSchema.optional(),
-	input: z.array(z.enum(["text", "image"])).optional(),
-	supportsTools: z.boolean().optional(),
-	cost: z
-		.object({
-			input: z.number().optional(),
-			output: z.number().optional(),
-			cacheRead: z.number().optional(),
-			cacheWrite: z.number().optional(),
-		})
-		.optional(),
-	premiumMultiplier: z.number().optional(),
-	contextWindow: z.number().optional(),
-	maxTokens: z.number().optional(),
-	omitMaxOutputTokens: z.boolean().optional(),
-	headers: z.record(z.string(), z.string()).optional(),
-	compat: OpenAICompatSchema.optional(),
-	contextPromotionTarget: z.string().min(1).optional(),
+export const ModelOverrideSchema = type({
+	"name?": "string",
+	"reasoning?": "boolean",
+	"thinking?": ModelThinkingSchema,
+	"input?": '("text" | "image")[]',
+	"supportsTools?": "boolean",
+	"cost?": {
+		"input?": "number",
+		"output?": "number",
+		"cacheRead?": "number",
+		"cacheWrite?": "number",
+	},
+	"premiumMultiplier?": "number",
+	"contextWindow?": "number",
+	"maxTokens?": "number",
+	"omitMaxOutputTokens?": "boolean",
+	"headers?": { "[string]": "string" },
+	"compat?": OpenAICompatSchema,
+	"contextPromotionTarget?": "string",
+}).narrow((value, ctx) => {
+	if (value.name !== undefined && typeof value.name === "string" && value.name.length === 0) {
+		return ctx.mustBe("name a non-empty string");
+	}
+	if (
+		value.contextPromotionTarget !== undefined &&
+		typeof value.contextPromotionTarget === "string" &&
+		value.contextPromotionTarget.length === 0
+	) {
+		return ctx.mustBe("contextPromotionTarget a non-empty string");
+	}
+	return true;
 });
 
-export type ModelOverride = z.infer<typeof ModelOverrideSchema>;
+export type ModelOverride = typeof ModelOverrideSchema.infer;
 
-export const ProviderDiscoverySchema = z.object({
-	type: z.enum(["ollama", "llama.cpp", "lm-studio", "openai-models-list", "proxy"]),
+export const ProviderDiscoverySchema = type({
+	type: '"ollama" | "llama.cpp" | "lm-studio" | "openai-models-list" | "proxy"',
 });
 
-export const ProviderAuthSchema = z.enum(["apiKey", "none", "oauth"]);
-
-export type ProviderAuthMode = z.infer<typeof ProviderAuthSchema>;
-export type ProviderDiscovery = z.infer<typeof ProviderDiscoverySchema>;
-
-const ProviderConfigSchema = z.object({
-	baseUrl: z.string().min(1).optional(),
-	apiKey: z.string().min(1).optional(),
-	api: z
-		.enum([
-			"openai-completions",
-			"openai-responses",
-			"openai-codex-responses",
-			"azure-openai-responses",
-			"anthropic-messages",
-			"google-generative-ai",
-			"google-gemini-cli",
-			"google-vertex",
-		])
-		.optional(),
-	headers: z.record(z.string(), z.string()).optional(),
-	compat: OpenAICompatSchema.optional(),
-	authHeader: z.boolean().optional(),
-	auth: ProviderAuthSchema.optional(),
-	discovery: ProviderDiscoverySchema.optional(),
-	models: z.array(ModelDefinitionSchema).optional(),
-	modelOverrides: z.record(z.string(), ModelOverrideSchema).optional(),
-	disableStrictTools: z.boolean().optional(),
+export const ProviderAuthSchema = type('"apiKey" | "none" | "oauth"');
+
+export type ProviderAuthMode = typeof ProviderAuthSchema.infer;
+export type ProviderDiscovery = typeof ProviderDiscoverySchema.infer;
+
+const ProviderConfigSchema = type({
+	"baseUrl?": "string",
+	"apiKey?": "string",
+	"api?":
+		'"openai-completions" | "openai-responses" | "openai-codex-responses" | "azure-openai-responses" | "anthropic-messages" | "google-generative-ai" | "google-gemini-cli" | "google-vertex"',
+	"headers?": { "[string]": "string" },
+	"compat?": OpenAICompatSchema,
+	"authHeader?": "boolean",
+	"auth?": ProviderAuthSchema,
+	"discovery?": ProviderDiscoverySchema,
+	"models?": ModelDefinitionSchema.array(),
+	"modelOverrides?": { "[string]": ModelOverrideSchema },
+	"disableStrictTools?": "boolean",
 	/**
 	 * Streaming transport override. When set to `"pi-native"`, omp dispatches
 	 * every model under this provider via the auth-gateway's
@@ -215,17 +218,41 @@ const ProviderConfigSchema = z.object({
 	 * provider's `baseUrl` must point at a compatible `omp auth-gateway`
 	 * and `apiKey` must carry the gateway bearer.
 	 */
-	transport: z.literal("pi-native").optional(),
+	"transport?": '"pi-native"',
+}).narrow((value, ctx) => {
+	if (value.baseUrl !== undefined && typeof value.baseUrl === "string" && value.baseUrl.length === 0) {
+		return ctx.mustBe("baseUrl a non-empty string");
+	}
+	if (value.apiKey !== undefined && typeof value.apiKey === "string" && value.apiKey.length === 0) {
+		return ctx.mustBe("apiKey a non-empty string");
+	}
+	return true;
 });
 
-const EquivalenceConfigSchema = z.object({
-	overrides: z.record(z.string(), z.string().min(1)).optional(),
-	exclude: z.array(z.string().min(1)).optional(),
+const EquivalenceConfigSchema = type({
+	"overrides?": { "[string]": "string" },
+	"exclude?": "string[]",
+}).narrow((value, ctx) => {
+	if (value.overrides !== undefined) {
+		for (const [, v] of Object.entries(value.overrides)) {
+			if (typeof v === "string" && v.length === 0) {
+				return ctx.mustBe("overrides values non-empty strings");
+			}
+		}
+	}
+	if (value.exclude !== undefined && Array.isArray(value.exclude)) {
+		for (const item of value.exclude) {
+			if (typeof item === "string" && item.length === 0) {
+				return ctx.mustBe("exclude items non-empty strings");
+			}
+		}
+	}
+	return true;
 });
 
-export const ModelsConfigSchema = z.object({
-	providers: z.record(z.string(), ProviderConfigSchema).optional(),
-	equivalence: EquivalenceConfigSchema.optional(),
+export const ModelsConfigSchema = type({
+	"providers?": { "[string]": ProviderConfigSchema },
+	"equivalence?": EquivalenceConfigSchema,
 });
 
-export type ModelsConfig = z.infer<typeof ModelsConfigSchema>;
+export type ModelsConfig = typeof ModelsConfigSchema.infer;

package/src/config/settings-schema.ts

@@ -897,6 +897,28 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"model.loopGuard.enabled": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "model",
+			group: "Thinking",
+			label: "Loop Guard",
+			description: "Enable automatic stream loop detection for Gemini and DeepSeek models",
+		},
+	},
+
+	"model.loopGuard.checkAssistantContent": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "model",
+			group: "Thinking",
+			label: "Loop Guard Scan Prose",
+			description: "Apply loop guard to assistant prose messages in addition to thinking logs",
+		},
+	},
+
 	repeatToolDescriptions: {
 		type: "boolean",
 		default: false,
@@ -1336,6 +1358,18 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"startup.showSplash": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "interaction",
+			group: "Startup & Updates",
+			label: "Show Startup Splash",
+			description:
+				"Show the full animated setup splash on normal interactive startup without rerunning setup. Quiet Startup still suppresses it.",
+		},
+	},
+
 	"startup.setupWizard": {
 		type: "boolean",
 		default: true,

package/src/discovery/builtin-rules/index.ts

@@ -19,6 +19,7 @@ import tsImportType from "./ts-import-type.md" with { type: "text" };
 import tsNoAny from "./ts-no-any.md" with { type: "text" };
 import tsNoDeprecatedLeftovers from "./ts-no-deprecated-leftovers.md" with { type: "text" };
 import tsNoDynamicImport from "./ts-no-dynamic-import.md" with { type: "text" };
+import tsNoInlineCastAccess from "./ts-no-inline-cast-access.md" with { type: "text" };
 import tsNoReturnType from "./ts-no-return-type.md" with { type: "text" };
 import tsNoTestTimers from "./ts-no-test-timers.md" with { type: "text" };
 import tsNoTinyFunctions from "./ts-no-tiny-functions.md" with { type: "text" };
@@ -45,6 +46,7 @@ export const BUILTIN_RULE_SOURCES: readonly BuiltinRuleSource[] = [
 	{ name: "ts-no-any", content: tsNoAny },
 	{ name: "ts-no-deprecated-leftovers", content: tsNoDeprecatedLeftovers },
 	{ name: "ts-no-dynamic-import", content: tsNoDynamicImport },
+	{ name: "ts-no-inline-cast-access", content: tsNoInlineCastAccess },
 	{ name: "ts-no-return-type", content: tsNoReturnType },
 	{ name: "ts-no-test-timers", content: tsNoTestTimers },
 	{ name: "ts-no-tiny-functions", content: tsNoTinyFunctions },

package/src/discovery/builtin-rules/ts-import-type.md

@@ -17,7 +17,7 @@ Use top-level `import type` declarations for type-only dependencies. NEVER write
 
 ```typescript
 // Bad — inline imports hide dependencies in signatures.
-function run(client: import("some-sdk").Client, input: import("zod/v4").infer<Schema>): Promise<Output>;
+function run(client: import("some-sdk").Client, input: import("arktype").infer<Schema>): Promise<Output>;
 
 // Bad — annotations become path dumps.
 const options: import("some-sdk/config").ClientOptions = { ... };
@@ -28,7 +28,7 @@ const options: import("some-sdk/config").ClientOptions = { ... };
 ```typescript
 import type { Client } from "some-sdk";
 import type { ClientOptions } from "some-sdk/config";
-import type { infer as Infer } from "zod/v4";
+import type { infer as Infer } from "arktype";
 
 function run(client: Client, input: Infer<Schema>): Promise<Output>;
 const options: ClientOptions = { ... };

package/src/discovery/builtin-rules/ts-no-any.md

@@ -1,5 +1,5 @@
 ---
-description: "Never use `any` in TypeScript annotations or assertions — use `unknown`, generics, or the actual type"
+description: "Never use `any` in TypeScript annotations or assertions — use `unknown`, generics, a schema parse at trust boundaries, or the actual type"
 condition: ": any|as any"
 scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
 ---
@@ -9,6 +9,7 @@ Never use `: any` or `as any`. They disable type checking exactly where the boun
 ## Use instead
 
 - `unknown` for unvalidated input.
+- A schema parse (Zod, Valibot, …; e.g. Zod v4 when it is already in the project) for untrusted or external input — validate once, then consume a typed value.
 - A domain type when the shape is known.
 - A generic when the caller supplies the shape.
 - A type guard when runtime checks establish shape.
@@ -25,7 +26,7 @@ function readId(value: any): any {
 // Good — validate unknown input.
 function readId(value: unknown): string | undefined {
 	if (value && typeof value === "object" && "id" in value) {
-		const candidate = (value as { id: unknown }).id;
+		const candidate = value.id; // `in` narrowing types this as unknown — no cast needed
 		return typeof candidate === "string" ? candidate : undefined;
 	}
 }
@@ -53,4 +54,12 @@ const config = { port: 3000 } as any as ServerConfig;
 const config = { port: 3000 } satisfies ServerConfig;
 ```
 
+## Choosing: guard vs schema vs unchecked cast
+
+| Situation | Reach for |
+| --- | --- |
+| Data from outside your control — network/RPC, parsed JSON, config files, env vars, CLI/IPC, persisted blobs — or a shape reused across the codebase | **Schema parse** (Zod/Valibot/…): runtime validation, typed output, and a clear error on bad shape |
+| In-process value the compiler merely lost track of — an `unknown` from a generic, a union to discriminate, a one-off read of a field or two | **Type guard** (`in` / `typeof`): no dependency, but it only checks what you write, so keep the checked surface small |
+| You genuinely know more than the compiler *and* a runtime check is impossible or meaningless — a well-known DOM node (`as HTMLElement`), structurally-identical types inference can't unify, a library type that is wrong or unexpressible, `as const` | **Unchecked cast** (`as` / `as unknown as T`): assign to a named const with a one-line reason; never for raw external input |
+
 If a library boundary truly requires an unchecked cast, use `as unknown as T` with a short reason. Never leave a bare `any`.

package/src/discovery/builtin-rules/ts-no-inline-cast-access.md

@@ -0,0 +1,55 @@
+---
+description: "Don't assert an inline object type and immediately read a property — `(x as { y: T }).y` trusts an unchecked shape; validate with a schema parse at trust boundaries, narrow with `in`/`typeof`, or use a validated named type"
+scope: "tool:edit(*.{ts,tsx,mts,cts}), tool:write(*.{ts,tsx,mts,cts})"
+interruptMode: tool-only
+astCondition:
+  - "($X as { $$$BODY }).$PROP"
+  - "($X as { $$$BODY })?.$PROP"
+  - "($X as { $$$BODY })[$IDX]"
+---
+
+**Don't assert an inline object type just to read a property.** `(value as { content: unknown }).content` fabricates a shape the compiler never verified, then trusts it for exactly one access. If `value` isn't that shape, the read is silently wrong and no type error ever fires.
+
+## Why it's wrong
+
+- The cast is an unchecked assertion — it suppresses the type error instead of proving the shape.
+- It localizes the lie to one expression, so the next reader can't tell whether the value was ever validated.
+- It almost always stands in for the real fix: runtime narrowing or a validated type at the boundary.
+
+## Avoid
+
+```ts
+const content = (value as { content: unknown }).content;
+const id = (resp as { data: { id: string } }).data.id;
+const name = (payload as { name?: string })?.name;
+const flag = (opts as { enabled: boolean })["enabled"];
+```
+
+## Use
+
+Prefer a schema parse at the boundary when a validator is available (Zod, Valibot, …) — validate once, then read from a fully typed value. If Zod is already in the project (e.g. Zod v4):
+
+```ts
+import { z } from "zod/v4";
+
+const Resp = z.object({ data: z.object({ id: z.string() }) });
+
+const resp = Resp.parse(raw); // throws on bad input; resp.data.id is typed string
+const id = resp.data.id;
+```
+
+For a one-off read of a single field, narrow with `in` / `typeof` so the access is actually checked — TypeScript infers `unknown` for the property after `"content" in value`:
+
+```ts
+if (value && typeof value === "object" && "content" in value) {
+	const content = value.content; // unknown — validate before use
+}
+```
+
+## Choosing: guard vs schema vs unchecked cast
+
+| Situation | Reach for |
+| --- | --- |
+| Data from outside your control — network/RPC, parsed JSON, config files, env vars, CLI/IPC, persisted blobs — or a shape reused across the codebase | **Schema parse** (Zod/Valibot/…): runtime validation, typed output, and a clear error on bad shape |
+| In-process value the compiler merely lost track of — an `unknown` from a generic, a union to discriminate, a one-off read of a field or two | **Type guard** (`in` / `typeof`): no dependency, but it only checks what you write, so keep the checked surface small |
+| You genuinely know more than the compiler *and* a runtime check is impossible or meaningless — a well-known DOM node (`as HTMLElement`), structurally-identical types inference can't unify, a library type that's wrong or unexpressible, `as const` | **Unchecked cast** (`as`): assign to a named const with a one-line reason; never for raw external input, never inlined into a member access |