@hobin/developer 0.1.10 → 0.1.11

package/README.md

@@ -84,7 +84,10 @@ details but are actually product, model, boundary, or evidence questions.
 | Branches lose rationale | Evidence replays with its branch |
 
 Developer coordinates judgment; Pi still reads, edits, runs, and tests the
-product with its normal tools.
+product with its normal tools. Across those judgments, an unchecked assertion,
+cast, non-null claim, or typed decode is never treated as evidence that a domain
+invariant holds: broader input must cross an owned parser or smart-constructor
+boundary whose success returns the refined value.
 
 ## How it works
 
@@ -118,6 +121,7 @@ and the plausible judgment routes add no useful information.
 | Clarify a feature | Separate meaning, constraints, examples, and blockers |
 | Model behavior | Enumerate cases, contracts, transitions, and guarantees |
 | Shape code | Expose data, interfaces, collaboration, state, and checks |
+| Refine input safely | Turn broader input into invariant-carrying domain values before dependent effects |
 | Inspect a design | Identify structural movement and model-code mismatch |
 | Review an abstraction | Keep, revise, split, reject, or defer the candidate |
 | Time a refactor | Separate behavior work and judge the cost of delay |

package/REFERENCE_ROUTING.md

@@ -200,7 +200,7 @@ separation behavior, and pass-but-wrong cases.
 | --- | --- | --- |
 | `abstraction-review` | `candidate-contract-review`, `failed-candidate-check`, `candidate-calibration` | review, failure localization, or promise-based calibration; no shadow construction |
 | `model` | `condition-space`, `contract-replacement`, `relational-constraints`, `temporal-behavior`, `proof-obligation`, `solver-result-boundary`, `logic-query-semantics`, `planning-model` | one model artifact per uncertainty and stop condition |
-| `sketch` | `data-driven-design`, `data-shape-template`, `composition-by-wishes`, `earned-abstraction`, `generative-recursion`, `accumulator-invariant`, `design-levels`, `representation-barrier`, `closure-interface`, `process-resources`, `state-history-order`, `generic-dispatch`, `meaning-preserving-conversion`, `language-semantics`, `runtime-compilation`, `responsibility-collaboration`, `variation-role`, `type-transition`, `selection-creation` | one implementable design question per route, with route-local common kernels only where required |
+| `sketch` | `data-driven-design`, `data-shape-template`, `composition-by-wishes`, `earned-abstraction`, `generative-recursion`, `accumulator-invariant`, `evidence-preserving-boundary`, `design-levels`, `representation-barrier`, `closure-interface`, `process-resources`, `state-history-order`, `generic-dispatch`, `meaning-preserving-conversion`, `language-semantics`, `runtime-compilation`, `responsibility-collaboration`, `variation-role`, `type-transition`, `selection-creation` | one implementable design question per route, with route-local common kernels only where required |
 | `signal` | `behavior-preserving-movement` | singleton |
 | `schedule` | `structural-timing-tradeoff` | singleton |
 | `naming-judgment` | `domain-sense-boundary` | singleton |

package/extensions/developer.ts

@@ -53,6 +53,7 @@ import {
 	applyDeveloperEvent,
 	canApplyDeveloperEvent,
 	developerSnapshot,
+	formatInvariantHandling,
 	initialState,
 	normalizeDeveloperEvent,
 	parseChoiceResponseSpec,
@@ -62,6 +63,7 @@ import {
 	type ChoiceResponseSpec,
 	type DeveloperState,
 	type ImplementationProfile,
+	type InvariantHandling,
 	type FocusEvent,
 	type JudgmentEvent,
 	type PendingQuestion,
@@ -215,6 +217,59 @@ interface ChoiceResponseSpecInput {
 	fields: ChoiceResponseFieldInput[];
 }
 
+type InvariantHandlingInput =
+	| {
+			kind: "not-applicable";
+			reason: string;
+	  }
+	| {
+			kind: "evidence-preserving-boundary";
+			raw_representation: string;
+			refined_representation: string;
+			producer: string;
+			failure: string;
+			first_effect: string;
+	  }
+	| {
+			kind: "trusted-compiler-gap";
+			assertion: string;
+			established_by: string;
+			limitation: string;
+			containment: string;
+			verification: string;
+	  };
+
+function invariantHandlingFromInput(
+	input: InvariantHandlingInput | undefined,
+): InvariantHandling {
+	if (!input) {
+		return {
+			kind: "not-applicable",
+			reason:
+				"Legacy direct tool execution omitted the now-required invariant-handling declaration.",
+		};
+	}
+	if (input.kind === "not-applicable") return input;
+	if (input.kind === "evidence-preserving-boundary") {
+		return {
+			kind: input.kind,
+			rawRepresentation: input.raw_representation,
+			refinedRepresentation: input.refined_representation,
+			producer: input.producer,
+			failure: input.failure,
+			firstEffect: input.first_effect,
+		};
+	}
+	return {
+		kind: input.kind,
+		assertion: input.assertion,
+		establishedBy: input.established_by,
+		limitation: input.limitation,
+		containment: input.containment,
+		verification: input.verification,
+	};
+}
+
 interface OpenQuestionInput {
 	question: string;
 	context?: string;
@@ -462,7 +517,9 @@ function protocolPrompt(
 		"- Adapt away from that topology when evidence makes a stage not applicable, but never jump directly from a resolved model to mutation: use sketch for feature implementation or signal for existing-code structural movement first.",
 		"- Route by the requested work product, not keywords: use sketch to create an original caller-facing interface, representation boundary, ownership map, or collaboration; use abstraction-review only when a concrete candidate surface already exists to keep/revise/split/reject/defer; use model first only when unresolved cases, rules, or policy can materially change that surface.",
 		`- Call ${ROUTE_TOOL} for exactly one concrete judgment or one green-to-green implementation movement.`,
-		"- Use target=implementation only when the next local movement, stable landing, and narrow verification are already justified; otherwise choose the focused skill whose scope fits the current question.",
+		"- Use target=implementation only when the next local movement, stable landing, narrow verification, and invariant handling are already justified; otherwise choose the focused skill whose scope fits the current question.",
+		"- Invariant gate: an unchecked assertion, cast, non-null claim, ignored conversion result, or typed deserialization target is not evidence that broader, external, persisted, legacy, or otherwise less-trusted input satisfies a domain invariant. Parse or construct a refined value whose success carries the learned information before dependent effects; validation followed by narrowing does not satisfy this gate.",
+		"- Every implementation route must classify invariant handling as not applicable, an evidence-preserving boundary, or a trusted compiler gap. A trusted compiler gap is valid only after a complete check or trusted contract already established the fact, the language cannot retain it, the unsafe operation is isolated to one owner, and a falsifier is named. Encountering a missing boundary requires sketch, not an implementation assertion.",
 		"- An implementation step has one observable difference and one structural or behavioral purpose. Stop when its failure is locally explainable and the repository is green, pausable, and reviewable.",
 		"- For implementation structural work intended to preserve behavior, set execution_profile=behavior-preserving-structure; omit the field for other implementation actions and every skill route.",
 		`- Follow the routed method, then close the route with ${JUDGMENT_TOOL}. After every implementation stable landing, route again from the new evidence before selecting another movement.`,
@@ -511,6 +568,11 @@ function protocolPrompt(
 		lines.push(
 			`Active route: ${state.activeRoute.routeId} · ${state.activeRoute.target} · ${state.activeRoute.question}`,
 		);
+		if (state.activeRoute.implementationStep) {
+			lines.push(
+				`Active invariant handling: ${formatInvariantHandling(state.activeRoute.implementationStep.invariantHandling)}. Stop and route sketch instead of mutating if this declaration is contradicted by the code.`,
+			);
+		}
 		if (state.activeRoute.methodLocation) {
 			lines.push(
 				`Active skill location: ${state.activeRoute.methodLocation}. Read it again if compaction or a later turn no longer contains the full instructions.`,
@@ -825,6 +887,83 @@ export default async function developer(pi: ExtensionAPI) {
 		},
 		{ additionalProperties: false },
 	);
+	const InvariantHandlingParam = Type.Union([
+		Type.Object(
+			{
+				kind: Type.Literal("not-applicable"),
+				reason: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"Why this movement neither creates nor narrows broader or less-trusted data into an invariant-carrying value",
+				}),
+			},
+			{ additionalProperties: false },
+		),
+		Type.Object(
+			{
+				kind: Type.Literal("evidence-preserving-boundary"),
+				raw_representation: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+				}),
+				refined_representation: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+				}),
+				producer: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"Parser, refinement function, or smart constructor whose success returns the refined value",
+				}),
+				failure: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+				}),
+				first_effect: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"First dependent domain effect allowed only after successful refinement",
+				}),
+			},
+			{ additionalProperties: false },
+		),
+		Type.Object(
+			{
+				kind: Type.Literal("trusted-compiler-gap"),
+				assertion: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+				}),
+				established_by: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"Complete check or trusted runtime contract that already established the asserted fact",
+				}),
+				limitation: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"Why ordinary language narrowing cannot retain the established fact",
+				}),
+				containment: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description: "Single parser or constructor owner containing the gap",
+				}),
+				verification: Type.String({
+					minLength: 1,
+					maxLength: MAX_EVIDENCE_CHARS,
+					description:
+						"Falsifier for the claimed prior evidence and containment",
+				}),
+			},
+			{ additionalProperties: false },
+		),
+	]);
 	const RouteParams = Type.Union([
 		Type.Object(
 			{
@@ -867,6 +1006,7 @@ export default async function developer(pi: ExtensionAPI) {
 					description:
 						"The narrowest check that can catch the likely break in this movement",
 				}),
+				invariant_handling: InvariantHandlingParam,
 				alternatives_considered: Type.Optional(
 					Type.Array(RouteAlternativeParam, {
 						maxItems: 6,
@@ -892,11 +1032,11 @@ export default async function developer(pi: ExtensionAPI) {
 		name: ROUTE_TOOL,
 		label: "Developer Route Question",
 		description:
-			"Route one concrete judgment or one green-to-green implementation movement. Route by work product: sketch creates an original design surface, abstraction-review judges an already-shaped candidate, and model settles unresolved conditions before design. Then use implementation stable landings and verify before completion.",
+			"Route one concrete judgment or one green-to-green implementation movement. Route by work product: sketch creates an original design surface, abstraction-review judges an already-shaped candidate, and model settles unresolved conditions before design. Implementation must declare how invariant-bearing values are constructed without unchecked narrowing. Then use stable landings and verify before completion.",
 		promptSnippet: "Choose how to handle one development question",
 		promptGuidelines: [
 			`Call ${ROUTE_TOOL} only when there is no active Developer route.`,
-			`Use ${ROUTE_TOOL} with the most focused skill supported by current evidence; choose sketch for an original interface or boundary, abstraction-review only for an already-shaped candidate, and model only for unresolved condition space. target=implementation requires one movement, one stable landing, and one narrow verification.`,
+			`Use ${ROUTE_TOOL} with the most focused skill supported by current evidence; choose sketch for an original interface or boundary, abstraction-review only for an already-shaped candidate, and model only for unresolved condition space. target=implementation requires one movement, one stable landing, one narrow verification, and a truthful invariant_handling declaration. Validation followed by an assertion is not an evidence-preserving boundary.`,
 			`When ${ROUTE_TOOL} follows an implementation judgment with another implementation route, cite the previous landing in known_evidence and record plausible skill routes in alternatives_considered instead of selecting implementation by momentum.`,
 			`After a resolved model, use sketch for first feature implementation framing or signal for existing-code structural movement before implementation mutation.`,
 		],
@@ -1041,6 +1181,10 @@ export default async function developer(pi: ExtensionAPI) {
 						"# Implementation action",
 						"",
 						"The next local action is already justified. Keep this route open while using Pi implementation tools and collecting evidence.",
+						"",
+						"## Invariant gate",
+						"",
+						"Follow the route's invariant-handling declaration. Broader or less-trusted input must become an invariant-carrying value through a parser, refinement function, or smart constructor before dependent effects. Validation followed by an assertion, cast, non-null claim, ignored conversion result, or typed decode is not evidence. If the declared handling is incomplete, stop without mutation and route sketch. Keep any trusted compiler gap isolated to its declared owner and verify its prior evidence and containment.",
 					].join("\n");
 				}
 
@@ -1059,6 +1203,11 @@ export default async function developer(pi: ExtensionAPI) {
 									? params.verification
 									: "Run the narrowest relevant check and inspect the resulting diff or output."
 								).trim(),
+								invariantHandling: invariantHandlingFromInput(
+									"invariant_handling" in params
+										? params.invariant_handling
+										: undefined,
+								),
 							}
 						: undefined;
 
@@ -1096,6 +1245,7 @@ export default async function developer(pi: ExtensionAPI) {
 								`Movement: ${implementationStep.movement}`,
 								`Stable landing: ${implementationStep.stopCondition}`,
 								`Narrow verification: ${implementationStep.verification}`,
+								`Invariant handling: ${formatInvariantHandling(implementationStep.invariantHandling)}`,
 								"Stop this implementation route at that landing, record the evidence, and route again before another movement.",
 							]
 						: []),
@@ -1173,7 +1323,8 @@ export default async function developer(pi: ExtensionAPI) {
 					context.lastComponent,
 				);
 			}
-			const event = result.details as RouteEvent | undefined;
+			const normalized = normalizeDeveloperEvent(result.details);
+			const event = normalized?.kind === "route" ? normalized : undefined;
 			let text = theme.fg("success", `routed ${routeRenderText(event)}`);
 			if (expanded && event) {
 				text += `\n${detailLine(theme, "route", event.routeId, "text")}`;
@@ -1207,6 +1358,7 @@ export default async function developer(pi: ExtensionAPI) {
 					text += `\n${detailLine(theme, "movement", event.implementationStep.movement, "text")}`;
 					text += `\n${detailLine(theme, "landing", event.implementationStep.stopCondition)}`;
 					text += `\n${detailLine(theme, "verify", event.implementationStep.verification)}`;
+					text += `\n${detailLine(theme, "invariant", formatInvariantHandling(event.implementationStep.invariantHandling))}`;
 				}
 			}
 			if (!expanded && event)
@@ -1382,7 +1534,9 @@ export default async function developer(pi: ExtensionAPI) {
 					context.lastComponent,
 				);
 			}
-			const event = result.details as ReferenceLoadEvent | undefined;
+			const normalized = normalizeDeveloperEvent(result.details);
+			const event =
+				normalized?.kind === "reference-load" ? normalized : undefined;
 			let text = theme.fg(
 				"success",
 				`loaded ${event?.path ?? "Developer reference"}`,
@@ -2011,7 +2165,8 @@ export default async function developer(pi: ExtensionAPI) {
 					context.lastComponent,
 				);
 			}
-			const event = result.details as JudgmentEvent | undefined;
+			const normalized = normalizeDeveloperEvent(result.details);
+			const event = normalized?.kind === "judgment" ? normalized : undefined;
 			const summary = judgmentRenderText(event);
 			let text =
 				event?.status === "resolved"

package/extensions/references/behavior-preserving-structural-change.md

@@ -46,7 +46,10 @@ For movement across a boundary, update one sender or caller at a time when the
 old and new forms can safely coexist. Confirm that each intermediate state is
 valid. Do not rely on a final large diff to explain which step changed behavior.
 A forwarding interface over the old implementation can be a temporary seam, but
-it is not evidence that the interface is a stable public abstraction.
+it is not evidence that the interface is a stable public abstraction. An
+assertion, cast, non-null claim, or unchecked typed decode is not a compatibility
+seam: if old or external data is broader than the new invariant, an adapter must
+parse and return the new representation or explicit failure.
 
 For suspected dead code, combine static references, dynamic reachability, and a
 scoped observation window appropriate to rare jobs, reflection, configuration,
@@ -192,10 +195,15 @@ The protocol is being misused when:
 - behavior work is hidden inside a structural label;
 - the route continues after a new human-owned policy question appears;
 - an intermediate state cannot safely run or be reviewed;
-- cleanup continues past the accepted pressure because the code could be nicer.
+- cleanup continues past the accepted pressure because the code could be nicer;
+- validation is preserved while its result is discarded and an assertion claims
+  the new representation.
 
 ## Source Trace
 
+- Alexis King, “Parse, don’t validate,” published November 5, 2019, for
+  evidence-preserving refinement before execution. The compatibility-seam and
+  migration wording is a Developer adaptation.
 - Sandi Metz, Katrina Owen, and TJ Stankus, *99 Bottles of OOP*, Second
   Edition, version 2.2.2, 2024: Chapters 3-5, pp. 51-137, especially
   pp. 58-71, 84-101, and 113-125, on methodical transformations, flocking,

package/extensions/skills.ts

@@ -86,13 +86,17 @@ export function availablePackageSkills(
 	return available;
 }
 
+function hasErrorCode(error: unknown, code: string): boolean {
+	return isRecord(error) && error.code === code;
+}
+
 export async function skillReferencePaths(skill: Skill): Promise<string[]> {
 	const referencesRoot = resolve(skill.baseDir, "references");
 	let entries: Dirent[];
 	try {
 		entries = await readdir(referencesRoot, { withFileTypes: true });
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		if (hasErrorCode(error, "ENOENT")) return [];
 		throw error;
 	}
 
@@ -248,7 +252,7 @@ export async function loadSkillReferencePolicy(
 	try {
 		source = await readFile(policyPath, "utf8");
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+		if (hasErrorCode(error, "ENOENT")) {
 			if (catalog.length > 0) {
 				throw new Error(
 					`Developer skill ${skill.name} has references but no reference-policy.json.`,

package/extensions/state.ts

@@ -46,6 +46,36 @@ export type QuestionUpdateStatus =
 export type ImplementationProfile =
 	| "ordinary"
 	| "behavior-preserving-structure";
+export type InvariantHandling =
+	| {
+			kind: "not-applicable";
+			reason: string;
+	  }
+	| {
+			kind: "evidence-preserving-boundary";
+			rawRepresentation: string;
+			refinedRepresentation: string;
+			producer: string;
+			failure: string;
+			firstEffect: string;
+	  }
+	| {
+			kind: "trusted-compiler-gap";
+			assertion: string;
+			establishedBy: string;
+			limitation: string;
+			containment: string;
+			verification: string;
+	  };
+
+export function formatInvariantHandling(value: InvariantHandling): string {
+	if (value.kind === "not-applicable")
+		return `not applicable — ${value.reason}`;
+	if (value.kind === "evidence-preserving-boundary") {
+		return `${value.rawRepresentation} -> ${value.refinedRepresentation} via ${value.producer}; failure=${value.failure}; first effect=${value.firstEffect}`;
+	}
+	return `trusted compiler gap — ${value.assertion}; established by ${value.establishedBy}; limitation=${value.limitation}; contained at ${value.containment}; check=${value.verification}`;
+}
 
 export interface ActivationEvent {
 	protocol: typeof PROTOCOL;
@@ -63,6 +93,7 @@ export interface ImplementationStepContract {
 	movement: string;
 	stopCondition: string;
 	verification: string;
+	invariantHandling: InvariantHandling;
 }
 
 export interface RouteAlternative {
@@ -248,6 +279,20 @@ function isStringArray(value: unknown): value is string[] {
 	);
 }
 
+function parseArray<T>(
+	value: unknown,
+	parse: (item: unknown) => T | undefined,
+): T[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const parsed: T[] = [];
+	for (const item of value) {
+		const result = parse(item);
+		if (result === undefined) return undefined;
+		parsed.push(result);
+	}
+	return parsed;
+}
+
 function isJudgmentStatus(value: unknown): value is JudgmentStatus {
 	return (
 		value === "resolved" ||
@@ -263,6 +308,51 @@ function isImplementationProfile(
 	return value === "ordinary" || value === "behavior-preserving-structure";
 }
 
+function parseInvariantHandling(value: unknown): InvariantHandling | undefined {
+	if (!isObject(value) || typeof value.kind !== "string") return undefined;
+	if (value.kind === "not-applicable") {
+		if (typeof value.reason !== "string") return undefined;
+		return { kind: value.kind, reason: value.reason };
+	}
+	if (value.kind === "evidence-preserving-boundary") {
+		if (
+			typeof value.rawRepresentation !== "string" ||
+			typeof value.refinedRepresentation !== "string" ||
+			typeof value.producer !== "string" ||
+			typeof value.failure !== "string" ||
+			typeof value.firstEffect !== "string"
+		) {
+			return undefined;
+		}
+		return {
+			kind: value.kind,
+			rawRepresentation: value.rawRepresentation,
+			refinedRepresentation: value.refinedRepresentation,
+			producer: value.producer,
+			failure: value.failure,
+			firstEffect: value.firstEffect,
+		};
+	}
+	if (value.kind !== "trusted-compiler-gap") return undefined;
+	if (
+		typeof value.assertion !== "string" ||
+		typeof value.establishedBy !== "string" ||
+		typeof value.limitation !== "string" ||
+		typeof value.containment !== "string" ||
+		typeof value.verification !== "string"
+	) {
+		return undefined;
+	}
+	return {
+		kind: value.kind,
+		assertion: value.assertion,
+		establishedBy: value.establishedBy,
+		limitation: value.limitation,
+		containment: value.containment,
+		verification: value.verification,
+	};
+}
+
 function parseImplementationStep(
 	value: unknown,
 ): ImplementationStepContract | undefined {
@@ -274,10 +364,20 @@ function parseImplementationStep(
 	) {
 		return undefined;
 	}
+	const invariantHandling =
+		value.invariantHandling === undefined
+			? {
+					kind: "not-applicable" as const,
+					reason:
+						"Legacy implementation route predates the invariant-handling declaration.",
+				}
+			: parseInvariantHandling(value.invariantHandling);
+	if (!invariantHandling) return undefined;
 	return {
 		movement: value.movement,
 		stopCondition: value.stopCondition,
 		verification: value.verification,
+		invariantHandling,
 	};
 }
 
@@ -622,19 +722,21 @@ export function normalizeDeveloperEvent(
 		) {
 			return undefined;
 		}
-		const consideredAlternatives = Array.isArray(value.consideredAlternatives)
-			? value.consideredAlternatives.map(parseRouteAlternative)
-			: [];
-		if (consideredAlternatives.some((alternative) => !alternative))
-			return undefined;
-		const referenceRoutes = Array.isArray(value.referenceRoutes)
-			? value.referenceRoutes.map(parseReferencePolicyRoute)
-			: [];
-		if (referenceRoutes.some((route) => !route)) return undefined;
-		const loadedReferences = Array.isArray(value.loadedReferences)
-			? value.loadedReferences.map(parseReferenceLoad)
-			: [];
-		if (loadedReferences.some((reference) => !reference)) return undefined;
+		const consideredAlternatives =
+			value.consideredAlternatives === undefined
+				? []
+				: parseArray(value.consideredAlternatives, parseRouteAlternative);
+		if (!consideredAlternatives) return undefined;
+		const referenceRoutes =
+			value.referenceRoutes === undefined
+				? []
+				: parseArray(value.referenceRoutes, parseReferencePolicyRoute);
+		if (!referenceRoutes) return undefined;
+		const loadedReferences =
+			value.loadedReferences === undefined
+				? []
+				: parseArray(value.loadedReferences, parseReferenceLoad);
+		if (!loadedReferences) return undefined;
 		return {
 			protocol: PROTOCOL,
 			kind: "route",
@@ -643,15 +745,15 @@ export function normalizeDeveloperEvent(
 			target: value.target,
 			reason: value.reason,
 			knownEvidence: value.knownEvidence,
-			consideredAlternatives: consideredAlternatives as RouteAlternative[],
+			consideredAlternatives,
 			availableReferences: value.availableReferences ?? [],
-			referenceRoutes: referenceRoutes as ReferencePolicyRoute[],
+			referenceRoutes,
 			referenceExemptionCriteria:
 				value.referenceExemptionCriteria === undefined
 					? undefined
 					: parseReferencePolicyExemption(value.referenceExemptionCriteria),
 			referencePolicySha256: value.referencePolicySha256,
-			loadedReferences: loadedReferences as ReferenceLoad[],
+			loadedReferences,
 			targetQuestionId: value.targetQuestionId,
 			methodLocation: value.methodLocation,
 			executionProfile: value.executionProfile,
@@ -698,21 +800,21 @@ export function normalizeDeveloperEvent(
 		return undefined;
 	}
 
-	const openedQuestions = value.openedQuestions.map(parsePendingQuestion);
-	if (openedQuestions.some((question) => !question)) return undefined;
-	const referenceBasis = Array.isArray(value.referenceBasis)
-		? value.referenceBasis.map(parseReferenceBasis)
-		: [];
-	if (referenceBasis.some((basis) => !basis)) return undefined;
-	if (
-		value.questionUpdates !== undefined &&
-		!Array.isArray(value.questionUpdates)
-	)
-		return undefined;
-	const questionUpdates = Array.isArray(value.questionUpdates)
-		? value.questionUpdates.map(parseQuestionUpdate)
-		: [];
-	if (questionUpdates.some((update) => !update)) return undefined;
+	const openedQuestions = parseArray(
+		value.openedQuestions,
+		parsePendingQuestion,
+	);
+	if (!openedQuestions) return undefined;
+	const referenceBasis =
+		value.referenceBasis === undefined
+			? []
+			: parseArray(value.referenceBasis, parseReferenceBasis);
+	if (!referenceBasis) return undefined;
+	const questionUpdates =
+		value.questionUpdates === undefined
+			? []
+			: parseArray(value.questionUpdates, parseQuestionUpdate);
+	if (!questionUpdates) return undefined;
 	return {
 		protocol: PROTOCOL,
 		kind: "judgment",
@@ -722,13 +824,13 @@ export function normalizeDeveloperEvent(
 		status: value.status,
 		result: value.result,
 		basis: value.basis,
-		referenceBasis: referenceBasis as ReferenceBasis[],
+		referenceBasis,
 		referenceExemption:
 			value.referenceExemption === undefined
 				? undefined
 				: parseReferenceExemption(value.referenceExemption),
-		openedQuestions: openedQuestions as PendingQuestion[],
-		questionUpdates: questionUpdates as QuestionUpdate[],
+		openedQuestions,
+		questionUpdates,
 		artifacts: value.artifacts,
 		changedArtifacts:
 			typeof value.changedArtifacts === "boolean"

package/extensions/tui.ts

@@ -22,6 +22,7 @@ import {
 } from "@earendil-works/pi-tui";
 
 import {
+	formatInvariantHandling,
 	protocolState,
 	type ChoiceResponseField,
 	type ChoiceResponseOption,
@@ -1416,6 +1417,10 @@ export class DeveloperHistoryDetailPanel {
 				addField("movement", route.implementationStep.movement);
 				addField("stop condition", route.implementationStep.stopCondition);
 				addField("verification", route.implementationStep.verification);
+				addField(
+					"invariant handling",
+					formatInvariantHandling(route.implementationStep.invariantHandling),
+				);
 			}
 			addValues("known evidence", route.knownEvidence);
 			addValues(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobin/developer",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Branch-aware judgment routing, evidence gates, and focused development skills for Pi.",
   "type": "module",
   "keywords": ["pi-package", "pi", "developer", "skills"],

package/skills/model/SKILL.md

@@ -78,8 +78,12 @@ states, transitions, or policy decisions invalidate the model.
 5. Select one specialized model only when contract, relation, time, exhaustive
    evidence, or search has an independent artifact and stop condition.
 6. State the ability lost and guarantee gained by the chosen representation.
-7. Place each guarantee at the appropriate type, boundary, validation, test,
-   property, proof, model check, or human decision.
+7. Place each guarantee at the appropriate type, boundary, parser, constructor,
+   database constraint, test, property, proof, model check, or human decision.
+   A validation result that carries no refined value and an unchecked assertion,
+   cast, non-null claim, or typed deserialization target cannot own a
+   representable-state guarantee. When raw and admitted domains differ, require
+   an evidence-bearing transition without designing its API.
 8. Derive counterexamples and verification targets without designing the API.
 
 ## Missing Evidence

package/skills/model/references/problem-modeling.md

@@ -134,8 +134,10 @@ to remain aligned.
 
 For every important rule, name the cheapest trustworthy owner and evidence target:
 
-- type for representable-state restrictions;
-- constructor or runtime validation for hostile input;
+- type or abstract representation for representable-state restrictions, but only
+  when every construction path establishes the restriction;
+- parser or smart constructor for hostile or broader input, returning the
+  invariant-carrying value or explicit failure rather than discarding the check;
 - contract for caller/callee meaning;
 - database constraint for persisted relational facts;
 - state transition owner for history-sensitive rules;
@@ -144,7 +146,11 @@ For every important rule, name the cheapest trustworthy owner and evidence targe
 - model, solver, or proof for bounded exhaustive relationships;
 - human decision for policy.
 
-An unchecked statement may guide design, but it is not evidence.
+An unchecked statement may guide design, but it is not evidence. Validation that
+returns only success, `Unit`, or `Bool` cannot by itself place a guarantee at a
+stronger type, and an assertion, cast, non-null claim, ignored conversion result,
+or typed deserialization target does not repair that gap. Record the required
+raw-to-refined transition and hand its concrete caller surface to `sketch`.
 
 ## Model Artifact
 
@@ -177,6 +183,10 @@ Separate rather than expanding this reference when:
 
 ## Source Trace
 
+- Alexis King, “Parse, don’t validate,” published November 5, 2019, for the
+  distinction between checks that discard learned information and fallible
+  transitions that return a refined representation. Concrete parser and
+  smart-constructor surfaces remain owned by `sketch`.
 - Hillel Wayne, *Logic for Programmers*, v0.14.0, 2026-05-04:
   Chapters 2-4, pp. 5-46, for predicates, quantifiers, ability/guarantee,
   specifications, and logic/runtime boundaries. Recorded beta defects are

package/skills/sketch/SKILL.md

@@ -50,10 +50,13 @@ sketch must be inspectable as an implementation shape, not only narrated in
 paragraphs. Produce:
 
 1. a compact case/check table;
-2. concrete data or state definitions;
+2. concrete data or state definitions, including raw and refined forms when an
+   input's provenance is broader than the accepted domain;
 3. wishful top-level code, pseudocode, or an interaction skeleton in a fenced
    code block;
 4. a wished-interface table with contract, owner, hidden detail, and stop check;
+   when raw and refined forms differ, show the parser or smart constructor whose
+   success returns the refined value and whose failure precedes dependent effects;
 5. a small ordered implementation queue and explicitly deferred abstractions;
 6. an ASCII flow, relation map, state transition, or boundary diagram whenever
    two or more components, states, or collaborations are materially related.
@@ -78,7 +81,10 @@ routing to the caller.
 
 Finish when the first implementation item is small enough to execute and check,
 and non-local or invariant-bearing candidates are explicit rather than silently
-assumed. `resolved` is not valid for a prose-only sketch: the output must show
+assumed. If broader, external, persisted, legacy, or otherwise less-trusted data
+enters the surface, `resolved` also requires an evidence-preserving transition to
+the domain representation; validation followed by an assertion is not such a
+transition. `resolved` is not valid for a prose-only sketch: the output must show
 the code or interaction skeleton and the checks that make the first item
 executable. Revisit when implementation evidence breaks the ownership or
 data-flow assumptions.
@@ -87,7 +93,9 @@ data-flow assumptions.
 
 1. Choose the strongest available source of intent and state its confidence.
 2. State the design unit's purpose in the user's language.
-3. Derive relevant data or state definitions and their ownership pressure.
+3. Derive relevant data or state definitions and their ownership pressure. Mark
+   provenance and the raw-to-refined boundary whenever callers cannot already
+   supply an invariant-carrying value. Treat unchecked narrowing as no evidence.
 4. List representative cases before choosing code shape.
 5. Name each independently unresolved design question and select only its routed
    extension; keep disputed meaning in `model`.

package/skills/sketch/reference-policy.json

@@ -4,12 +4,12 @@
     {
       "id": "data-driven-design",
       "question": "How do accepted data meanings and examples determine the first executable function surface?",
-      "trigger": "Product information, variants, examples, or tests should determine the function skeleton, and no narrower template, composition, generation, or accumulator question is primary.",
+      "trigger": "Product information, variants, examples, or tests should determine the function skeleton, and no narrower template, composition, generation, accumulator, or evidence-preserving boundary question is primary.",
       "method_step": "derive data definition, interpretation, examples, purpose, template, completed shape, and first executable item",
       "references": ["references/data-driven-design.md"],
       "artifacts": ["the six ordered design artifacts", "repository contradictions mapped to those artifacts", "a bounded first item and propagation check"],
       "stop": "Accepted data and behavior examples constrain an executable skeleton with contradictions and compatibility visible.",
-      "separate_when": "Template shape, composition, earned abstraction, generated problems, or accumulated knowledge has an independent artifact."
+      "separate_when": "Template shape, composition, earned abstraction, generated problems, accumulated knowledge, or raw-to-refined construction has an independent artifact."
     },
     {
       "id": "data-shape-template",
@@ -66,6 +66,16 @@
       "stop": "The invariant explains initial, step, and final states and every semantic/resource delta is explicit.",
       "separate_when": "Problems are generated, carried data is persistent product history, or a concrete cache surface needs review."
     },
+    {
+      "id": "evidence-preserving-boundary",
+      "question": "How does less-trusted or less-structured input become a domain value that carries the established invariant?",
+      "trigger": "External, serialized, persisted, legacy, foreign, unknown, nullable, or overly broad input must become an accepted domain value; checks are repeated, return no refined value, occur after effects, or are followed by an assertion, cast, non-null claim, unchecked decode, or public raw construction.",
+      "method_step": "derive raw provenance, refined representation, parser or smart-constructor success/failure, construction owner, first-effect boundary, escape audit, and any bounded compiler gap",
+      "references": ["references/evidence-preserving-boundaries.md"],
+      "artifacts": ["a raw-to-refined boundary pipeline", "a parser/smart-constructor and failure contract", "a construction/escape, effect-order, and trusted-compiler-gap audit"],
+      "stop": "Every core construction path returns the invariant-carrying representation or explicit failure before dependent effects, with no unchecked narrowing or public raw-constructor bypass.",
+      "separate_when": "Admitted values or failure policy are disputed, alternate representations/public laws are independently consequential, a valid domain event changes type, or old/new compatibility remains unsettled."
+    },
     {
       "id": "design-levels",
       "question": "Which vocabulary, owner, and dependency direction make this caller contract truthful?",
@@ -74,7 +84,7 @@
       "references": ["references/design-levels-and-boundaries.md"],
       "artifacts": ["a caller-purpose and level map", "contract/owner/hidden choice/assumptions", "an alternate implementation or falsifier"],
       "stop": "Dependencies use truthful vocabulary, guarantees have owners, and lower-level change does not force unrelated callers.",
-      "separate_when": "Representation, closure, process, state, dispatch, conversion, language, runtime, responsibility, or variation has its own output."
+      "separate_when": "Evidence-preserving input refinement, representation, closure, process, state, dispatch, conversion, language, runtime, responsibility, or variation has its own output."
     },
     {
       "id": "representation-barrier",

package/skills/sketch/references/evidence-preserving-boundaries.md

@@ -0,0 +1,200 @@
+# Evidence-Preserving Boundaries
+
+Use this reference when less-trusted or less-structured input must become a domain
+value whose type or abstract representation carries an accepted invariant. The
+input may be bytes, JSON, form values, command-line arguments, database rows,
+legacy records, framework payloads, foreign values, or an overly broad in-memory
+type. Parsing here means any fallible transformation from a weaker
+representation to a stronger one; it is not limited to text.
+
+## Information Must Survive The Check
+
+Two operations may perform the same runtime checks while establishing different
+contracts:
+
+```text
+validate : Raw -> Result<Unit, BoundaryError>
+parse    : Raw -> Result<Domain, BoundaryError>
+```
+
+`validate` reports only success or failure. Unless its result narrows the value
+in a scope the compiler preserves, later code still receives `Raw` and must
+repeat the check, trust a comment, or assert `Domain`. `parse` returns the more
+precise value and makes the learned information necessary for execution.
+
+Treat these as evidence-destroying by default:
+
+```text
+validate(raw); cast raw to Domain
+JSON.decode(bytes) as Domain
+lookup(key)! where absence has domain meaning
+construct Domain through public raw fields
+```
+
+A type assertion, cast, non-null assertion, ignored conversion result, or typed
+deserialization target is not evidence that an invariant holds.
+
+## Draw The Refinement Boundary
+
+Derive this pipeline before choosing library syntax:
+
+```text
+external / raw / legacy representation
+                |
+                | parse / refine / smart constructor
+                | failure is explicit here
+                v
+       invariant-carrying domain value
+                |
+                | total core operations
+                v
+             domain effects
+```
+
+Record:
+
+```text
+raw representation and provenance
+accepted domain representation
+invariant learned at the transition
+parser or smart-constructor signature
+success and failure result
+single construction owner
+first domain effect allowed after success
+legacy, persistence, and re-entry paths
+```
+
+Push the proof burden toward the earliest boundary that has enough information,
+but no further. Authorization or a small resource guard may precede expensive
+parsing when abuse resistance requires it; those checks must not perform the
+domain mutation that depends on parsed input. Parsing may use several passes or
+select a later parser from an earlier discriminator as long as execution does
+not consume partially parsed domain data.
+
+## Choose A Stronger Representation
+
+Prefer the most precise representation the current language and repository can
+reasonably support:
+
+- a product type when required fields must be present together;
+- a sum type when cases have different meanings or fields;
+- a non-empty, bounded, normalized, branded, opaque, or capability-bearing type
+  when that restriction removes a real downstream branch;
+- a map or set when uniqueness or duplicate policy is accepted;
+- an abstract type with a smart constructor when the host type system cannot
+  directly encode the invariant.
+
+Do not call a narrower representation better until the excluded ability is known
+to be unnecessary. The accepted domain comes from `model`; this route owns the
+boundary that constructs it.
+
+## Wished Interface
+
+Use the target language's ordinary result and error conventions. The important
+shape is that success carries `Domain`:
+
+```text
+parseOrder : UnknownInput -> Result<Order, OrderInputError>
+placeOrder : Order -> Effect<PlacementResult>
+
+handle(input):
+  order <- parseOrder(input)
+  placeOrder(order)
+```
+
+Throwing at an application edge, returning an option/either/result, or using a
+checked constructor can all be valid. A predicate or assertion function can also
+preserve information when the language genuinely narrows the checked value in
+the only scope where it is consumed. What is not valid is checking one value and
+then separately claiming a stronger type without a compiler-visible or
+abstraction-visible connection.
+
+## Construction And Escape Audit
+
+List every way `Domain` can enter the core:
+
+| Path | Input provenance | Establishes invariant by | Produces | Bypass risk |
+| --- | --- | --- | --- | --- |
+| public parser | external raw value | complete boundary checks | `Domain` or failure | expected path |
+| smart constructor | broad in-memory value | constructor checks | abstract `Domain` or failure | expected path |
+| deserializer | persisted or wire value | parser plus compatibility policy | `Domain` or failure | unchecked typed decode |
+| internal constructor | already refined fields | private construction law | `Domain` | public/raw export |
+| test factory | test data | public or equivalent checked path | `Domain` | unrealistic invalid fixtures |
+
+A claimed invariant is only as strong as its weakest construction path. Search
+for raw constructors, object literals, reflection, ORM hydration, generated
+adapters, test factories, casts, suppressions, and legacy re-entry points.
+
+## Trusted Compiler Gaps
+
+Sometimes a complete check establishes a fact that the host type system cannot
+retain. Do not spread assertions to compensate. Isolate the smallest exception
+inside the one parser or smart-constructor owner and record:
+
+```text
+exact assertion or unsafe operation
+fact already established
+complete check or trusted contract that established it
+why ordinary narrowing cannot express the fact
+containment boundary
+falsifying test, type check, or structural inspection
+```
+
+Literal-preservation syntax and framework types already guaranteed by a runtime
+schema are not the same as asserting hostile input into a domain type. The
+burden is still on the exception to name its prior evidence. If that evidence is
+missing, return to the parser design instead of documenting a wish.
+
+## Shotgun And Effect Check
+
+Reject a design when parsing or validation is mixed through processing code:
+
+- consumers repeat checks for the same invariant;
+- a late branch can discover malformed input after writes, sends, or mutations;
+- every core function reserves an "impossible" failure despite an earlier check;
+- compatibility adapters emit partially refined values;
+- normalized and raw forms remain mutable and can drift apart.
+
+Parse before the first domain effect. If staging or streaming makes one complete
+up-front parse impractical, define an explicit phase or transaction boundary and
+ensure each effect consumes a value whose required invariant is already carried
+by that phase's representation.
+
+## Artifact
+
+```text
+Raw representation and provenance:
+Refined domain representation:
+Invariant gained and ability lost:
+Parser/smart-constructor signature:
+Failure representation:
+Construction owner and escape audit:
+First domain effect after success:
+Legacy/persistence/re-entry handling:
+Trusted compiler gaps, or none:
+Negative, bypass, and effect-order checks:
+```
+
+## Stop And Separation
+
+Stop when every core construction path either produces the refined domain value
+through the declared parser/constructor or fails explicitly, invalid input is
+rejected before the domain effect that depends on it, and no unchecked narrowing
+or public raw constructor claims the invariant.
+
+Return to `model` when the admitted values or failure policy are disputed. Use
+`representation-barrier` when alternate internal representations and public laws
+are independently consequential, `type-transition` when an accepted domain
+event transforms one valid domain type into another, and `contract-replacement`
+when old and new boundary compatibility remains unsettled.
+
+## Source Trace
+
+- Alexis King, “Parse, don’t validate,” published November 5, 2019: the
+  `NonEmpty` example, validation-versus-parsing return-type contrast, boundary
+  parsing and shotgun-parsing discussion, practical duplicate-key example, and
+  guidance on precise datatypes, proof placement, multi-pass parsing,
+  denormalization, abstract datatypes, and bounded exceptions.
+- The construction-path audit, trusted-compiler-gap record, effect-order check,
+  repository compatibility paths, and language-neutral assertion taxonomy are
+  Developer adaptations of that source's type-driven design argument.

package/skills/verify/SKILL.md

@@ -74,8 +74,11 @@ after code changes, new evidence, changed claims, or source-provenance changes.
 1. Extract the exact claims from the request, accepted decisions, implementation
    report, invariant, or model.
 2. Attach concrete evidence to each claim and classify its strength.
-3. Check constraints, forbidden cases, transitions, callers, and abstraction
-   stop checks when they are part of the claim.
+3. Check constraints, forbidden cases, transitions, callers, abstraction stop
+   checks, and every construction or re-entry path for invariant-carrying values
+   when they are part of the claim. Validation followed by an assertion, a
+   public raw constructor, unchecked deserialization, or a domain effect before
+   parsing is a pass-but-wrong shape, not type evidence.
 4. Distinguish verifier execution from verifier relevance.
 5. Ask what wrong implementation could still pass and name its concrete shape.
 6. Narrow any passing claim that is broader than its evidence.

package/skills/verify/references/verifier-selection-and-pass-but-wrong.md

@@ -26,7 +26,7 @@ Separate independently falsifiable claims:
 - user or caller behavior;
 - forbidden and boundary cases;
 - data multiplicity and preservation;
-- type or API contract;
+- type or API contract, including raw-to-refined construction and re-entry paths;
 - state transition and history;
 - representation or ownership boundary;
 - source/version compatibility;
@@ -102,10 +102,17 @@ calibrations by failure mechanism rather than by book.
 | database schema behavior is preserved | row content matches | labels or function-valued predicates changed | inspect schema and execute predicates/integrity checks |
 | temporal implementation is correct | each enum state is reachable | stale or duplicate event commits twice | ordered trace with stale, retry, duplicate, and concurrency |
 | abstraction is safe | public tests pass | callers still depend on fields, load order, or hidden default | leak search, fake variant, and real caller rewrite |
+| domain type carries its invariant | happy input passes and typecheck is green | validation returns no refined value, then a cast/assertion claims the domain type | inspect every construction path; require parser/smart-constructor success to return the domain value |
+| invalid input cannot affect domain state | negative parser test passes | a write, send, mutation, or partial update happens before parsing completes | effect-order integration check with invalid and partially valid input |
+| construction boundary is closed | public parser tests pass | raw constructor, ORM hydration, test factory, or legacy adapter bypasses the parser | constructor/export/re-entry search plus a direct-bypass type or runtime check |
 | package/source compatibility holds | workspace tests pass | packed artifact or installed version lacks changed files | inspect tarball/fresh install and bind provenance |
 
 A verifier for one row does not support another. In particular, location,
 residual, representation, and downstream tolerances are not interchangeable.
+A typecheck proves only that the program follows the declared types; an
+unchecked narrowing operation can make a false declaration typecheck. Pair
+compile-time evidence with construction-path and boundary evidence whenever the
+type itself is part of the claim.
 
 ## Formal And Search Result Boundaries
 
@@ -165,6 +172,10 @@ Unverified claims and residual risk:
 
 ## Source Trace
 
+- Alexis King, “Parse, don’t validate,” published November 5, 2019, for the
+  distinction between a check that discards information and a parser that
+  returns a refined value, plus the parsing-before-execution boundary. The
+  construction-path and effect-order verifier rows are Developer adaptations.
 - Hillel Wayne, *Logic for Programmers*, v0.14.0:
   Chapters 3-6 and 9-11, pp. 23-155, for logical/runtime preservation, partial
   specifications, generated properties, proof limits, bounded models, and solver