diff --git a/src/content/docs/docs.mdx b/src/content/docs/docs.mdx index dca971e..946ebb3 100644 --- a/src/content/docs/docs.mdx +++ b/src/content/docs/docs.mdx @@ -42,5 +42,7 @@ Protocol features that depend on the older server-initiated request model are outside the current fault set. :::note[Current scope] -Failure Lab runs scenarios against its own built-in MCP server. External client orchestration, JUnit output, and additional protocol faults are not implemented yet. +Failure Lab runs scenarios against its own built-in MCP server. A generic target-client adapter +contract is available as the foundation for external-client support, but CLI orchestration is not +implemented yet. JUnit output and additional protocol faults are also not implemented. ::: diff --git a/src/content/docs/docs/architecture.mdx b/src/content/docs/docs/architecture.mdx index cc77711..7c4d0cf 100644 --- a/src/content/docs/docs/architecture.mdx +++ b/src/content/docs/docs/architecture.mdx @@ -1,6 +1,6 @@ --- title: Architecture -description: How Failure Lab separates server construction, transport, tools, and scenario execution. +description: How Failure Lab separates server construction, transports, scenarios, and target-client adapters. --- ## Server and transport path @@ -95,6 +95,52 @@ flowchart TD _Figure 3. Observer verification and failure handling._ -:::note[Deliberate boundary] -The current architecture is not a proxy and does not orchestrate external MCP clients. Target-client adapters remain future work. +## Target-client adapter boundary + +The target-client adapter contract is the foundation for future external-client orchestration. It +is generic: the core does not contain branches for particular MCP hosts, clients, servers, or +transports. + +```mermaid +flowchart LR + Orchestrator[Failure Lab orchestration] -->|setup with time budget| Adapter[Target-client adapter] + Adapter --> Session[Target-client session] + Orchestrator -->|execute scenario| Session + Orchestrator -->|observe post-condition| Session + Orchestrator -->|cancel operation| Session + Orchestrator -->|cleanup on every exit path| Session + Session --> Recording[Typed operation observation] +``` + +_Figure 4. The adapter owns a target-client session; orchestration owns its lifecycle._ + +Each operation has a caller-provided, positive, finite timeout. Its recording includes the +operation and correlation ID, monotonic start and end values, duration, and one terminal outcome: +`success`, `error`, `timeout`, `cancelled`, or `transport_loss`. Successful recordings contain a +typed value; unsuccessful recordings contain a structured failure. + +### Lifecycle and ownership + +Failure Lab orchestration owns operation IDs, time budgets, scenario inputs, expectation +evaluation, and reporting. The adapter owns only the target-client resources it creates during +setup. A successful setup returns one session through which execution, observation, cancellation, +and cleanup occur. + +The orchestrator must request cleanup after every successful setup, including when execution, +observation, or cancellation fails. Adapter cleanup must be idempotent so repeated or concurrent +requests have the same externally visible effect as a single request. + +The contract and deterministic test adapter live in: + +```text +src/targetClientAdapter.ts +src/testing/deterministicFakeTargetClientAdapter.ts +``` + +The fake performs no I/O and models operation timing from a supplied plan. It tests the boundary +without duplicating the server’s fault implementations. + +:::note[Current limitation] +The adapter contract is available, but the CLI does not yet orchestrate external MCP clients. MCP +Failure Lab is not a proxy, and it does not include special handling for any third-party MCP host. :::