Tool Connectors composition, configuration, and governance

This chapter explains how a connector enters a process. The extension binds ports to adapters only. Vendor SDK registration, order, configuration, and startup validation belong to the host composition root.

1. Selection algorithm

Each connector executes this independently. bool.TryParse makes missing or invalid configuration fail closed.

2. Correct registration order

// ① Register the SDK first so service-type detection can see it.
if (configuration.GetValue<bool>("Connectors:Ocr:Enabled"))
    services.AddOCRService(configuration.GetSection("Connectors:Ocr"));

// ② Select the real or unavailable port implementation afterward.
services.AddBitzOrcasToolConnectorsAdapters(configuration);

// ③ Startup verification must distinguish resolution from readiness.

The XML example in source shows adapter selection before SDK registration. Following it selects unavailable. Because selection uses TryAddScoped, a later invocation does not replace that earlier port registration. This order sensitivity is a current implementation fact.

3. What TryAdd means

TryAddScoped<TPort,TAdapter> preserves an earlier registration. That supports explicit host/test overrides, but can also preserve an accidental unavailable or foreign implementation.

A production composition root should:

1. centralize registration;
2. assert the final descriptor in startup tests;
3. document override order;
4. never rely on a second invocation to repair selection;
5. diagnose Enabled=true plus missing SDK as a deployment error.

4. Current host delivery

BitzOrcas.Api.csproj references Contracts for governance visibility. It does not reference Infrastructure or call any Tool Connector or vendor SDK registration.

It is accurate to say the commercial catalog can package the two projects and the ports/adapters can be reused by another host. It is inaccurate to claim that the primary API exposes, entitles, or health-checks them.

5. Four distinct controls

Disabled composition should make the dependency unavailable. A disabled feature should produce a stable request rejection. Permission and domain rejection need their own stable errors.

6. Duplicate governance

The owner-local module now declares module, dependency, permissions, and features. Platform Application still carries a duplicate legacy declaration and a stale explanatory comment.

Migration should verify discovery from Contracts, add uniqueness tests for module/permission/feature keys, delete the legacy declaration, refresh governance snapshots, and verify identical catalogs in database and database-less hosts.

7. Secret and configuration safety

Enabled flags can live in regular configuration. Provider credentials cannot live in source or logs. Bind secret references, validate required fields at startup, and avoid dumping option objects.

iManage needs a protected tenant-to-credential mapping. Crawler proxy/cookies and OCR data directories are operational assets and must not be request-controlled.

8. Health layers

DI resolution proves only that a real or unavailable object exists. Separate checks should cover:

• composition: selected adapter;
• configuration: required provider options;
• connectivity: reachable provider;
• capability: safe, minimal operation;
• dependency state: rate limit, breaker, and credentials.

Readiness must not upload, checkout, or navigate to an arbitrary URL. Probes need bounded cost and no tenant data.

9. Startup verification example

bool expected = configuration.GetValue<bool>("Connectors:Ocr:Enabled");

await using AsyncServiceScope scope = provider.CreateAsyncScope();
IOcrPort port = scope.ServiceProvider.GetRequiredService<IOcrPort>();

// Current integration tests can inspect the implementation type.
// A public capability descriptor is preferable for production health.
if (expected && port is UnavailableOcrPort)
    throw new InvalidOperationException("OCR enabled but adapter unavailable.");

10. Release configuration record

For each connector document SDK compatibility, defaults, required secrets, network/SSL/proxy needs, timeout/concurrency/rate limits, data location, health/alerts, disable/rollback, and credential rotation.

Configuration review must happen before traffic and after any SDK upgrade.

The release record should also name:

• the owning team and escalation route;
• the exact Host and environment;
• expected adapter implementation type;
• SDK package and provider API version;
• secret owner and rotation interval;
• network egress allowlist;
• feature rollout cohort;
• rollback trigger and maximum rollback time.

11. Composition contract tests

Parameterize three connectors across Disabled, Enabled without SDK, Enabled with SDK, and invalid configuration. Add cases for pre-registered override and wrong order.

// ① Build an enabled configuration without registering IOCRService.
var services = new ServiceCollection();
var configuration = BuildConfig(("Connectors:Ocr:Enabled", "true"));

services.AddBitzOrcasToolConnectorsAdapters(configuration);

// ② Port resolution succeeds, but the selected implementation remains unavailable.
using ServiceProvider provider = services.BuildServiceProvider();
using IServiceScope scope = provider.CreateScope();
var port = scope.ServiceProvider.GetRequiredService<IOcrPort>();

Assert.IsType<UnavailableOcrPort>(port);

12. Source checks

# ① Inspect conditional selection and service detection.
rg -n "TryAddScoped|IsSdkServiceRegistered|EnabledKey" \
  src/Platform/ToolConnectors -g '*.cs'
# ② Compare governance declarations and host composition.
rg -n "ToolConnectorsModule|tool-connectors\." src/Platform -g '*.cs'
rg -n "AddBitzOrcasToolConnectorsAdapters" src/Hosts -g '*.cs'

Back to Tool Connectors