[chr-hertel]

Step 4 of #495: RegistryInterface now extends a catalog, a resolver and a writer role, and request handlers depend on the role they use. Existing implementations keep working.

setLazyLoading(true) now also defers loading into a registry from setRegistry(). The builder wraps it in an internal decorator instead of handing the registry a loader, so no Registry has to adopt one after construction - that was the objection on #494, happy to hear if this shape still has the same problem.

Capabilities are now detected when a request asks for them, since nothing reads them earlier - so the builder doesn't need to know what is loaded and a server advertises what it actually holds.

[BC Break] with that explicit call, a registry you read directly stays empty until the server first reads it. Without the call it still loads at build.

[BC Break] initialize, server/discover and subscriptions/listen run a pending load, so the handshake is no longer free of discovery. Configuration::$capabilities becomes capabilities().

Compared to #495, DeferredRegistryInterface has loadFrom() and isLoaded() instead of isEmpty().

[Copilot]

🟡 Changes recommended

Capability detection can trigger a supplied registry’s loader during build() despite lazy loading, potentially freezing a cold source empty or failing the build.

1 open issue

• Lazy loading triggers supplied registry loader during build · New

What changed in this PR

This PR advances #495 by splitting registry responsibilities and adding opt-in deferred loading for caller-supplied registries, while preserving their default eager loading.

Changes:

• Introduces catalog, resolver and writer interfaces, with request handlers depending on the role they use.
• Adds a lazy registry decorator and a load-lifecycle interface for custom registries.
• Adds regression tests and documents the loading behavior and compatibility change.

File	Description
tests/​Unit/​Server/​BuilderTest.php	Covers supplied-registry loading and capability detection.
tests/​Unit/​Capability/​Registry/​LazyRegistryTest.php	Tests deferred loading, retries and event suppression.
src/​Server/​Stateless/​StandardHeaderValidator.php	Depends on the resolver interface.
src/​Server/​Handler/​Request/​ResourceUnsubscribeHandler.php	Depends on the resolver interface.
src/​Server/​Handler/​Request/​ResourceSubscribeHandler.php	Depends on the resolver interface.
src/​Server/​Handler/​Request/​ReadResourceHandler.php	Depends on the resolver interface.
src/​Server/​Handler/​Request/​ListToolsHandler.php	Depends on the catalog interface.
src/​Server/​Handler/​Request/​ListResourceTemplatesHandler.php	Depends on the catalog interface.
src/​Server/​Handler/​Request/​ListResourcesHandler.php	Depends on the catalog interface.
src/​Server/​Handler/​Request/​ListPromptsHandler.php	Depends on the catalog interface.
src/​Server/​Handler/​Request/​GetPromptHandler.php	Depends on the resolver interface.
src/​Server/​Handler/​Request/​CompletionCompleteHandler.php	Depends on the resolver interface.
src/​Server/​Handler/​Request/​CallToolHandler.php	Depends on the resolver interface.
src/​Server/​Builder.php	Wraps explicitly deferred custom registries and adjusts capability detection.
src/​Capability/​RegistryInterface.php	Extends the three role interfaces.
src/​Capability/​Registry/​LazyRegistry.php	Adds the deferred-loading decorator.
src/​Capability/​Registry.php	Implements the load-lifecycle interface.
src/​Capability/​ElementWriterInterface.php	Defines registration and removal operations.
src/​Capability/​ElementResolverInterface.php	Defines individual element lookups.
src/​Capability/​ElementCatalogInterface.php	Defines paginated element listings.
src/​Capability/​DeferredRegistryInterface.php	Defines loading and event-suppression contracts.
docs/​run/​server-builder.md	Documents custom-registry loading options.
CHANGELOG.md	Records the new interfaces and compatibility change.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Unresolved registry-loading defects can prevent retries after a failed concurrent load and trigger premature capability detection for third-party lazy registries.

2 open issues

• Do not mark deferred registry loaded before loading succeeds · New
• Treat registries without a load-state contract as opaque · New

1 resolved since last review

• Lazy loading triggers supplied registry loader during build

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Critical issues remain: capability-loading exceptions can escape request handling and terminate the stdio loop, while concurrent loading can incorrectly mark the decorator loaded and permanently lose registrations.

2 open issues

• Do not mark the decorator loaded before its loader runs · New
• Catch capability loader errors in subscriptions/listen · New

2 resolved since last review

• Do not mark deferred registry loaded before loading succeeds
• Treat registries without a load-state contract as opaque

_{Review effort: Balanced}