export function acquireClientRunContext(
  opts: ClientConformanceRunOptions,
): Effect.Effect<
  ClientConformanceRunContext,
  ToxicControlError | RealServerAcquireError | RealClientLifecycleError,
  Scope.Scope
>

export function acquireFixture(
  ctx: ClientConformanceRunContext,
  category: PropertyCategory,
  propertyName: string,
): Effect.Effect<ClientFixture, PropertyUnavailable, Scope.Scope>

export function awaitConnection(
  testServer: TestServer,
  timeoutMs = DEFAULT_ACCEPT_TIMEOUT_MS,
): Effect.Effect<TestServerConnection, TransportIoError>

export interface ClientConformanceRunContext {
  readonly testServer: TestServer;
  readonly realClientFactory: (
    args: RealClientFactoryArgs,
  ) => Effect.Effect<RealClientHandle, RealClientLifecycleError, Scope.Scope>;
  readonly handshakeWindow: ClientHandshakeWindow;
  readonly toxiproxy: ToxiproxyClient | null;
  readonly opts: ClientConformanceRunOptions;
  readonly seed: number;
  readonly artifacts: Ref.Ref<ReadonlyArray<ConformanceArtifact>>;
}

export interface ClientConformanceRunOptions {
  readonly tiers: ReadonlyArray<"A" | "B" | "C" | "D" | "E">;
  readonly realClient: (
    args: RealClientFactoryArgs,
  ) => Effect.Effect<RealClientHandle, RealClientLifecycleError, Scope.Scope>;
  readonly replaySeed?: number;
  readonly numRuns?: number;
  readonly manageToxiproxy?: boolean;
  readonly toxiproxyUrl?: string;
  readonly artifactDir?: string;

  /**
   * If `true`, TestServer binds behind a Toxiproxy upstream matching the
   * adversity-tier `downstream` port; otherwise a direct bind. Default:
   * `true` when `tiers` includes `"D"`.
   */
  readonly bindThroughToxiproxy?: boolean;
}

export interface ClientConformanceSuiteOptions {
  /**
   * Factory for the real MoltZap client under test, owned by the
   * suite's Scope. Receives `testServerUrl` from the suite so the real
   * client can point its WS socket at the bound TestServer substrate.
   */
  readonly realClient: (args: {
    readonly testServerUrl: string;
  }) => Effect.Effect<RealClientHandle, RealClientLifecycleError, Scope.Scope>;

  /**
   * Toxiproxy control-plane URL. When `null`, adversity properties are
   * registered and surface `PropertyUnavailable`. Mirrors server-side
   * behavior.
   */
  readonly toxiproxyUrl?: string | null;
  readonly replaySeed?: number;
  readonly numRuns?: number;
  readonly artifactDir?: string;

  /**
   * Default `true`. When `true`, TestServer binds behind Toxiproxy so
   * adversity toxics shape the wire between TestServer and the real
   * client. Set to `false` only for debugging.
   */
  readonly bindThroughToxiproxy?: boolean;
}

export interface ClientFixture {
  readonly handle: RealClientHandle;
  readonly connection: TestServerConnection;
  readonly window: ClientHandshakeWindow;
}

export interface ClientHandshakeWindow {
  readonly freshEmissionTag: Effect.Effect<string>;
  readonly emitTaggedNotification: (opts: {
    readonly connection: TestServerConnection;
    readonly base: NotificationFrame;
    readonly emissionTag: string;
  }) => Effect.Effect<string>;
  readonly emitTaggedResponse: (opts: {
    readonly connection: TestServerConnection;
    readonly base: ResponseFrame;
    readonly emissionTag: string;
  }) => Effect.Effect<string>;
  readonly awaitHandshakeComplete: Effect.Effect<
    void,
    RealClientLifecycleError
  >;
}

export interface ClientHandshakeWindow

export function collectTagged(
  handle: RealClientHandle,
  predicate: (tag: string) => boolean,
  opts: { readonly expected: number; readonly budgetMs: number },
): Effect.Effect<ReadonlyArray<TaggedObservation>>

export function freshTag(window: ClientHandshakeWindow): Effect.Effect<string>

export function invariant(
  category: PropertyCategory,
  name: string,
  reason: string,
): PropertyInvariantViolation

export interface JointConformanceSuiteOptions {
  readonly realServer?: ClientConformanceSuiteOptions["realClient"] extends never
    ? never
    : unknown;
  readonly realClient?: ClientConformanceSuiteOptions["realClient"];
  readonly toxiproxyUrl?: string | null;
  readonly replaySeed?: number;
  readonly numRuns?: number;
  readonly artifactDir?: string;
  readonly bindThroughToxiproxy?: boolean;
}

export function lookupTagForRawBytes(rawBytes: Uint8Array): string | null

export function makeClientHandshakeWindow(
  handle: RealClientHandle,
): Effect.Effect<ClientHandshakeWindow, never, Scope.Scope>

export function notificationParamsRecord(
  params: unknown,
): Readonly<Record<string, unknown>>

export interface ObservedNotification {
  readonly emissionTag: string | null;
  readonly decoded: unknown;
  readonly rawBytes: Uint8Array;
  readonly observedAtMs: number;
}

export interface RealClientCloseEvent {
  readonly code: number;
  readonly reason: string;
  readonly observedAtMs: number;
}

export interface RealClientFactoryArgs {
  readonly testServerUrl: string;
}

export interface RealClientHandle {
  /**
   * Stable identifier emitted in the connect frame's `agentId` field.
   * Used to correlate TestServer-observed inbound frames to this client.
   */
  readonly agentId: string;

  /**
   * Fully-connected promise — resolves after the handshake completes and
   * the client is ready to receive notifications. Property bodies await this
   * before scripting TestServer emissions so the handshake-noise guard
   * window is closed (see `ClientHandshakeWindow`).
   */
  readonly ready: Effect.Effect<void, RealClientLifecycleError>;

  /**
   * Real client's public notification-subscriber surface. Every captured notification
   * is tagged with the property-authored `emissionId` when the property
   * uses `ClientHandshakeWindow.emitTaggedNotification`; predicates filter by
   * that tag to exclude handshake-noise frames.
   */
  readonly notifications: RealClientNotificationSubscriber;

  /**
   * Real client's documented RPC caller. B1 / B4 / D5 predicates invoke
   * this and assert on the returned promise's resolution / rejection.
   */
  readonly call: RealClientRpcCaller;

  /**
   * Real client's documented close / disconnect lifecycle signal. D6
   * predicate awaits this on slow-close and asserts it resolves within
   * the reap deadline.
   */
  readonly closeSignal: Effect.Effect<RealClientCloseEvent>;

  /**
   * Scope-release hook. The runner's Scope calls this on teardown; a
   * close that throws surfaces as `RealClientLifecycleError`.
   */
  readonly close: Effect.Effect<void, RealClientLifecycleError>;
}

export class RealClientLifecycleError extends Data.TaggedError(
  "RealClientLifecycleError",
)<{
  readonly cause: unknown;
}> {}

export type RealClientNotificationFilter = (
  notification: DecodedNotification<AnyNotificationDefinition>,
) => boolean;

export interface RealClientNotificationSubscriber {
  readonly subscribe: (
    filter?: RealClientNotificationFilter,
  ) => Effect.Effect<RealClientSubscription, RealClientLifecycleError>;
  readonly snapshot: Effect.Effect<ReadonlyArray<ObservedNotification>>;
}

export interface RealClientRpcCaller {
  readonly call: (
    method: string,
    params: unknown,
  ) => Effect.Effect<ResponseFrame | NotificationFrame, RealClientRpcError>;
}

export class RealClientRpcError extends Data.TaggedError("RealClientRpcError")<{
  readonly cause: unknown;
  readonly documentedErrorTag: string | null;
  readonly kind:
    | "timeout"
    | "server-error"
    | "malformed-response"
    | "disconnected";
  readonly method: string;
}> {}

export interface RealClientSubscription {
  readonly id: string;
  readonly unsubscribe: Effect.Effect<void>;
}

export function registerAllClientProperties(
  ctx: ClientConformanceRunContext,
): void

export function registerArchiveLifecycleClient(
  ctx: ClientConformanceRunContext,
): void

export function registerEmittedFrameTag(raw: string, tag: string): void

export function registerFanOutCardinalityClient(
  ctx: ClientConformanceRunContext,
): void

export function registerLatencyResilienceClient(
  ctx: ClientConformanceRunContext,
): void

export function registerMalformedFrameHandlingClient(
  ctx: ClientConformanceRunContext,
): void

export function registerModelEquivalenceClient(
  ctx: ClientConformanceRunContext,
): void

export function registerNotificationWellFormednessClient(
  ctx: ClientConformanceRunContext,
): void

export function registerPayloadOpacityClient(
  ctx: ClientConformanceRunContext,
): void

export function registerRequestIdUniquenessClient(
  ctx: ClientConformanceRunContext,
): void

export function registerResetPeerRecoveryClient(
  ctx: ClientConformanceRunContext,
): void

export function registerSchemaExhaustiveFuzzClient(
  ctx: ClientConformanceRunContext,
): void

export function registerSlicerFramingClient(
  ctx: ClientConformanceRunContext,
): void

export function registerSlowCloseCleanupClient(
  ctx: ClientConformanceRunContext,
): void

export function registerTaskBoundaryIsolationClient(
  ctx: ClientConformanceRunContext,
): void

export function registerTimeoutSurfaceClient(
  ctx: ClientConformanceRunContext,
): void

export function runAutoHandshakeResponder(
  connection: TestServerConnection,
  agentId: string,
): Effect.Effect<void, never, Scope.Scope>

export function runClientConformanceSuite(
  opts: ClientConformanceSuiteOptions,
): Effect.Effect<
  SuiteResult,
  ToxicControlError | RealServerAcquireError | RealClientLifecycleError
>

export function subscribeAll(
  handle: RealClientHandle,
): Effect.Effect<void, PropertyUnavailable, Scope.Scope>

export interface TaggedObservation {
  readonly tag: string;
  readonly raw: Uint8Array;
  readonly decoded: NotificationFrame;
  readonly params: Readonly<Record<string, unknown>>;
  readonly notificationName: NotificationFrame["method"];
}