Summary

Consolidate the first low-conflict set of duplicated and stale internal type contracts identified by the repository-wide type-surface audit.

Problem to solve

Three internal areas currently maintain parallel type descriptions instead of one canonical owner:

1. Script .d.mts companions omit live exports, so tests copy shadow module interfaces and use as unknown as casts.
2. src/gateway/client.ts redeclares the gateway-client package option/event contract, while the package repeats protocol guards and error shapes.
3. PluginRegistry marks collections optional even though the loader always initializes them, producing widespread defensive fallback branches.

These duplicate contracts can drift silently, obscure real invariants, and add substantial review/navigation overhead.

Proposed solution

Implement three independently reviewable PRs:

• Make the affected script declaration companions authoritative and delete test-local shadow interfaces.
• Make packages/gateway-client and packages/gateway-protocol the canonical client/guard owners, leaving only core-owned construction policy in src/gateway/client.ts.
• Make canonically initialized PluginRegistry collections required and delete unreachable fallback branches. Lifecycle-state union work is explicitly out of scope for this wave.

Each PR should preserve runtime behavior, include focused regression/type proof, and avoid compatibility aliases unless a shipped public contract is demonstrated.

Alternatives considered

• Keep the duplicate types and add more synchronization tests: rejected because it preserves multiple mutable sources of truth.
• Combine all three into one PR: rejected because the ownership and validation surfaces are independent.
• Perform the larger provider/plugin lifecycle redesign now: deferred to later waves to keep this foundation bounded and reviewable.

Impact

Affected: OpenClaw maintainers and contributors working on scripts/CI, gateway clients, and plugin loading.

Severity: Medium maintainability and correctness risk.

Frequency: Every change to the duplicated contracts requires manual synchronization; drift is already present in declaration companions.

Consequence: unsafe casts, redundant branches, slower review, and increased chance of contract divergence.

Evidence/examples

The read-only audit identified the primary surfaces at:

• scripts/test-projects.test-support.d.mts, scripts/docs-link-audit.d.mts, scripts/ci-changed-scope.d.mts, scripts/lib/vitest-local-scheduling.d.mts
• src/gateway/client.ts, packages/gateway-client/src/client.ts, packages/gateway-protocol/src/index.ts
• src/plugins/registry-types.ts

Conservative expected reduction for this wave: approximately 305-345 net lines while reducing the number of canonical type paths.