refactor: consolidate coercion contracts (#122458)

* refactor: consolidate coercion contracts

Centralize exact string, record, numeric, date, Boolean, argument, and structured-error coercions while preserving call-site semantics.

Migrate canonical-name collisions and deprecated internal SDK bypasses, deleting 55 net production/tooling lines. Expand declaration ownership enforcement to 101 allowed helpers and add a narrow export-completeness audit.

* fix: preserve standalone script coercions

Keep copied Control UI tooling self-contained and retain the trusted release harness module-relative source seam when the harness runs against an old target cwd.

test/e2e/qa-lab/config/cli-channel-picker.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { pathToFileURL } from "node:url";
 import { stripAnsiSequences } from "../../../../packages/terminal-core/src/ansi.js";
+import { coerceErrorMessage as formatErrorMessage } from "../../../../scripts/lib/error-format.mts";
 import { createQaScriptEvidenceWriter } from "../runtime/script-evidence.js";
 
 const SCENARIO_ID = "cli-channel-picker";
@@ -18,10 +19,6 @@ type ProducerOptions = {
   timeoutMs: number;
 };
 
-function formatErrorMessage(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function sanitizePickerTranscript(transcript: string) {
   return stripAnsiSequences(transcript).replaceAll(
     /123456(?:(?::|…)[A-Za-z0-9_…-]*)?/gu,

test/e2e/qa-lab/media/hosted-media-provider-live.ts

@@ -6,6 +6,7 @@ import {
   QA_EVIDENCE_FILENAME,
   type QaEvidenceSummaryJson,
 } from "../../../../extensions/qa-lab/api.js";
+import { coerceErrorMessage as formatErrorMessage } from "../../../../scripts/lib/error-format.mts";
 import { spawnPnpmRunner as _spawnPnpmRunner } from "../../../../scripts/pnpm-runner.mts";
 import {
   createQaScriptBlockedStatusTracker,
@@ -170,10 +171,6 @@ function formatProviderList(providers: Iterable<string>): string {
   return [...providers].toSorted().join(", ");
 }
 
-function formatErrorMessage(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function spawnLivePnpm(params: { pnpmArgs: string[]; env: NodeJS.ProcessEnv }) {
   return _spawnPnpmRunner({
     pnpmArgs: params.pnpmArgs,

test/e2e/qa-lab/plugins/clawhub-release-candidate-install.ts

@@ -8,6 +8,7 @@ import {
   QA_EVIDENCE_FILENAME,
   type QaEvidenceSummaryJson,
 } from "../../../../extensions/qa-lab/api.js";
+import { coerceErrorMessage as formatErrorMessage } from "../../../../scripts/lib/error-format.mts";
 import { createBoundedChildOutput } from "../../../helpers/bounded-child-output.js";
 import {
   createQaScriptBlockedStatusTracker,
@@ -165,10 +166,6 @@ async function writeJson(filePath: string, value: unknown) {
   await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
 
-function formatErrorMessage(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 async function resolveCandidateTarball(options: ProducerOptions) {
   const explicitTarball = process.env[options.tarballEnv]?.trim();
   if (explicitTarball) {

test/e2e/qa-lab/runtime/browser-plugin-profiles-packaged.ts

@@ -5,6 +5,7 @@ import {
   QA_EVIDENCE_FILENAME,
   type QaEvidenceSummaryJson,
 } from "../../../../extensions/qa-lab/api.js";
+import { coerceErrorMessage as formatError } from "../../../../scripts/lib/error-format.mts";
 import { createQaScriptEvidenceWriter } from "./script-evidence.js";
 
 const SCENARIO_ID = "browser-plugin-profiles-packaged";
@@ -20,10 +21,6 @@ type DockerOutcome = {
   signal: NodeJS.Signals | null;
 };
 
-function formatError(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 export function parseBrowserPluginProfilesOptions(args: string[]): ProducerOptions {
   if (args.length !== 2 || args[0] !== "--artifact-base" || !args[1]) {
     throw new Error("usage: --artifact-base <output-directory>");

test/e2e/qa-lab/runtime/docker-artifact-proof.ts

@@ -7,6 +7,7 @@ import {
   QA_EVIDENCE_FILENAME,
   type QaEvidenceSummaryJson,
 } from "../../../../extensions/qa-lab/api.js";
+import { coerceErrorMessage as formatErrorMessage } from "../../../../scripts/lib/error-format.mts";
 import { createQaScriptEvidenceWriter } from "./script-evidence.js";
 
 const SOURCE_PATH = "test/e2e/qa-lab/runtime/docker-artifact-proof.ts";
@@ -42,10 +43,6 @@ type ArtifactIdentity = {
   scenarioId: string;
 };
 
-function formatErrorMessage(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function isProofLane(value: string): value is DockerArtifactProofLane {
   return Object.hasOwn(PROOFS, value);
 }

test/e2e/qa-lab/runtime/gateway-protocol-artifacts.ts

@@ -11,6 +11,7 @@ import {
   type QaEvidenceSummaryJson,
 } from "../../../../extensions/qa-lab/api.js";
 import { ProtocolSchemas } from "../../../../packages/gateway-protocol/src/schema/protocol-schemas.js";
+import { coerceErrorMessage as formatErrorMessage } from "../../../../scripts/lib/error-format.mts";
 import { listCoreGatewayMethodMetadata } from "../../../../src/gateway/methods/core-descriptors.js";
 import { createQaScriptEvidenceWriter } from "./script-evidence.js";
 
@@ -187,10 +188,6 @@ export function buildPortableSwiftAnyCodableSource(source: string) {
   return source.includes("import CoreFoundation") ? source : `import CoreFoundation\n${source}`;
 }
 
-function formatErrorMessage(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 export function parseGatewayProtocolArtifactOptions(
   args: readonly string[],
   cwd = process.cwd(),

test/e2e/qa-lab/runtime/managed-gateway-service-lifecycle-product-proof.ts

@@ -7,6 +7,7 @@ import {
   type QaEvidenceSummaryJson,
   validateQaEvidenceSummaryJson,
 } from "../../../../extensions/qa-lab/api.js";
+import { coerceErrorMessage as formatErrorMessage } from "../../../../scripts/lib/error-format.mts";
 import { createQaScriptEvidenceWriter } from "./script-evidence.js";
 
 const SCENARIO_ID = "managed-gateway-service-lifecycle";
@@ -91,10 +92,6 @@ if (process.platform === "darwin") {
   });
 }
 
-function formatErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function parseOptions(args: string[]): ProducerOptions {
   if (args.length !== 2 || args[0] !== "--artifact-base" || !args[1]) {
     throw new Error("usage: --artifact-base <output-directory>");

test/e2e/qa-lab/runtime/update-run-package-self-upgrade.ts

@@ -7,6 +7,7 @@ import {
   QA_EVIDENCE_FILENAME,
   type QaEvidenceSummaryJson,
 } from "../../../../extensions/qa-lab/api.js";
+import { coerceErrorMessage as formatErrorMessage } from "../../../../scripts/lib/error-format.mts";
 import { createQaScriptEvidenceWriter } from "./script-evidence.js";
 
 const SOURCE_PATH = "test/e2e/qa-lab/runtime/update-run-package-self-upgrade.ts";
@@ -44,10 +45,6 @@ type UpdateRunSelfUpgradeSummary = {
   };
 };
 
-function formatErrorMessage(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 export function parseUpdateRunSelfUpgradeOptions(args: string[]): ProducerOptions {
   let artifactBase: string | undefined;
   for (let index = 0; index < args.length; index += 1) {

test/e2e/qa-lab/tui/tui-pty-evidence-producer.ts

@@ -11,6 +11,7 @@ import {
   type QaEvidenceSummaryJson,
   type QaSeedScenarioWithSource,
 } from "../../../../extensions/qa-lab/api.js";
+import { coerceErrorMessage as formatErrorMessage } from "../../../../scripts/lib/error-format.mts";
 import { createQaScriptEvidenceWriter } from "../runtime/script-evidence.js";
 
 const SOURCE_PATH = "test/e2e/qa-lab/tui/tui-pty-evidence-producer.ts";
@@ -89,10 +90,6 @@ type ProofMatrixCase = TuiPtyCase & {
   matchedAssertions: string[];
 };
 
-function formatErrorMessage(error: unknown) {
-  return error instanceof Error ? error.message : String(error);
-}
-
 function readOptionValue(argv: readonly string[], index: number, option: string) {
   const value = argv[index + 1];
   if (!value || value.startsWith("--")) {