test(core): define registration, well-known, and mixed-version SDK compatibility

[jrschumacher]

Release classification

Parent: #3996 — Roadmap to OpenTDF v1.

Proposed class: v1-assurance. Score: 5/10 (correctness/reliability 1/3; compatibility 3/3; operability 1/2; explicit v1 dependency 0/2). No explicit release dependency is assumed. Scores describe release necessity, not implementation value; confirmed security/correctness/compatibility failures override the score.

Roadmap reference: ROAD-S08.

Motivation

Platform discovery is already a supported collection of contracts, not a blank slate for a new capability system. Services register entries into a process-global well-known map; the platform exposes both Connect and GET /.well-known/opentdf-configuration; duplicate top-level namespaces are rejected; and selected code updates base_key. Authentication centrally exempts well-known, health, and KAS public-key routes. A remote SDK fetches platform configuration during construction unless configuration is supplied, then discovers the token endpoint from platform_issuer. IPC skips remote discovery because the server supplies its connection/configuration during bootstrap.

Sources: well-known map, registration, HTTP and Connect handlers, public route allowlist, and SDK construction/discovery plus getPlatformConfiguration / OIDC discovery. The SDK also contains targeted compatibility fallback when a newer key-mapping RPC is unimplemented (tests); fallback is not a universal rule for discovery failures.

Scoped deliverable

Publish a route/key/ownership inventory and a focused old/new compatibility matrix: old SDK with current platform, current SDK with a fixture representing the supported older platform surface, metadata present/absent, and newer optional RPC returning Unimplemented where a fallback already exists. Verify that additive unknown well-known keys do not break supported SDK parsing and that existing keys/routes retain shape and authentication classification.

Non-goals: no new capability schema or endpoint, no typed registry, no legacy removal, no fleet-wide capability claim, and no silent fallback on timeout, malformed metadata, auth failure, or ambiguous side-effecting errors.

Acceptance tests

• Inventory covers Connect/HTTP well-known, health, and KAS public-key routes and current top-level keys produced by built-ins.
• Existing keys such as platform_issuer, health, and base_key retain documented shape/ownership.
• Name the supported SDK/platform versions under test; a pinned older SDK ignores an additive unknown top-level key.
• Current SDK behavior is explicit when well-known data is absent, malformed, or unreachable.
• A legacy fallback test exists only for an already-supported absence/Unimplemented case; other failures remain errors.
• Remote and IPC bootstrap differences are documented without promising public capability negotiation.

Rollout and impact

Actual controls: callers may supply platform configuration; IPC bypasses remote discovery; targeted legacy fallbacks exist; no capability-publication gate exists.
Proposed controls: characterization only. Future additive metadata should get an explicit publication/adoption control and mixed-version tests.

Downstream changes: none. Complexity medium for stable version fixtures; coupling high across registration, auth, SDK, and public metadata. Dependencies: none; recommended before any typed capability publication.

v1 rationale

Mixed-version and discovery behavior are public compatibility concerns. The characterization is a candidate v1 gate if these SDK/platform combinations are in the support contract; capability expansion itself can remain post-v1.

Delivery flags

Required downstream adaptation	Existing feature gate	High complexity	High coupling
NO for characterization	N/A: tests/docs only	CONDITIONAL: version fixtures	YES: SDK, registration, auth and metadata