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.

src/plugin-sdk/file-lock.ts

@@ -6,6 +6,7 @@ import {
   drainFileLockManagerForTest,
   resetFileLockManagerForTest,
 } from "@openclaw/fs-safe/file-lock";
+import { asNullableRecord } from "@openclaw/normalization-core/record-coerce";
 import {
   isLockOwnerDefinitelyStale,
   shouldRemoveDeadOwnerOrExpiredLock,
@@ -86,9 +87,7 @@ function createCurrentProcessLockPayload(): Record<string, unknown> {
 }
 
 function asLockPayload(payload: unknown): Record<string, unknown> | null {
-  return payload && typeof payload === "object" && !Array.isArray(payload)
-    ? (payload as Record<string, unknown>)
-    : null;
+  return asNullableRecord(payload);
 }
 
 function sameStatValue(left: number | bigint, right: number | bigint): boolean {

src/plugin-sdk/provider-catalog-live-runtime.ts

@@ -1,3 +1,4 @@
+import { normalizeOptionalString as readLiveModelCatalogString } from "../../packages/normalization-core/src/string-coerce.js";
 import { isNonSecretApiKeyMarker } from "../agents/model-auth-markers.js";
 import { cancelUnreadResponseBody, readResponseWithLimit } from "../infra/http-body.js";
 import { retainSafeHeadersForCrossOriginRedirect } from "../infra/net/redirect-headers.js";
@@ -209,10 +210,6 @@ async function readLiveModelCatalogJson(response: Response, timeoutMs: number):
   return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(buffer));
 }
 
-function readLiveModelCatalogString(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
-}
-
 function readLiveModelCatalogNextUrl(body: unknown): string | undefined {
   const record = readLiveModelCatalogRecord(body);
   if (!record) {

src/plugin-sdk/provider-onboard.ts

@@ -5,6 +5,7 @@ import {
   findNormalizedProviderKey,
   normalizeProviderId,
 } from "@openclaw/model-catalog-core/provider-id";
+import { isRecord } from "../../packages/normalization-core/src/record-coerce.js";
 import { resolvePrimaryStringValue } from "../../packages/normalization-core/src/string-coerce.js";
 import { ensureStaticModelAllowlistEntry } from "../agents/model-allowlist-entry.js";
 import { normalizeConfiguredProviderCatalogModelId } from "../agents/model-ref-shared.js";
@@ -294,7 +295,7 @@ export function createAliasOnlyPresetAppliers(params: {
 function isMergeableProviderConfig(
   value: ModelProviderConfig | undefined,
 ): value is ModelProviderConfig {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+  return isRecord(value);
 }
 
 function mergeOnboardProviderRequest(

src/plugin-sdk/test-helpers/provider-discovery-contract.ts

@@ -1,4 +1,6 @@
 // Provider discovery contract helpers define reusable discovery tests for provider plugins.
+import { asNullableRecord } from "@openclaw/normalization-core/record-coerce";
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { runProviderCatalog } from "../../plugins/provider-discovery.js";
 import {
@@ -162,10 +164,7 @@ function installDiscoveryHooks(state: DiscoveryState, options: DiscoveryContract
           "Editor-Version": "vscode/1.96.2",
           "User-Agent": "GitHubCopilotChat/0.26.7",
         })),
-        coerceSecretRef: (value: unknown) =>
-          value && typeof value === "object" && !Array.isArray(value)
-            ? (value as Record<string, unknown>)
-            : null,
+        coerceSecretRef: asNullableRecord,
         ensureApiKeyFromOptionEnvOrPrompt: vi.fn(),
         ensureAuthProfileStore: ensureAuthProfileStoreMock,
         listProfilesForProvider: listProfilesForProviderMock,
@@ -176,8 +175,7 @@ function installDiscoveryHooks(state: DiscoveryState, options: DiscoveryContract
             ? trimmed
             : "github.com";
         },
-        normalizeOptionalSecretInput: (value: unknown) =>
-          typeof value === "string" && value.trim() ? value.trim() : undefined,
+        normalizeOptionalSecretInput: normalizeOptionalString,
         resolveNonEnvSecretRefApiKeyMarker: (source: unknown) =>
           typeof source === "string" ? source : "",
         upsertAuthProfile: vi.fn(),