@cavi-ai/api-client/testing

export type CapabilityClientConformanceReport = {
    ok: boolean;
    probes: CapabilityClientProbe[];
    rejections: CapabilityClientProbe[];
};

export type CapabilityClientProbe = {
    call: string;
    resolved: boolean;
    ok?: boolean;
    error?: unknown;
};

export type HttpTransportConformanceFixture = FixtureFor<"http", HttpTransportConformanceObservation>;

export type HttpTransportConformanceObservation = TransportConformanceSharedObservation & Readonly<{
    kind: "http";
    requests: readonly HttpRequestObservation[];
}>;

/**
 * The non-throwing contract, made checkable: call one representative method
 * per facade surface and verify each RESOLVES (ok:true or ok:false) instead
 * of rejecting. Probes run against an undeclared/unwired client — nothing
 * should escalate to the auth/unknown carve-outs.
 *
 * `events.subscribe` is probed like every other gated surface: it resolves a
 * `CapabilityResult` (`ok:false` on a bare/undeclared client). On the rare
 * client where it resolves `ok:true` (a live subscription), the probe disposes
 * the returned `RuntimeEventSubscription` so the inspector never leaks a live
 * subscription against a real backend.
 */
export declare function inspectCapabilityClientConformance(client: CapabilityClient): Promise<CapabilityClientConformanceReport>;

/**
 * Exercise a KanbanClient's core methods and validate the canonical shape.
 *
 * NOTE: this MUTATES the target backend — it creates a card, updates and moves
 * it, then deletes it. Run it against a disposable board, not production data.
 */
export declare function inspectKanbanConformance(client: KanbanClient): Promise<KanbanConformanceReport>;

export declare function inspectRuntimeProviderConformance(fixture: RuntimeProviderConformanceFixture): Promise<RuntimeProviderConformanceReport>;

/** Exercise a TeamDirectory's resolution contract. Read-only (no mutation). */
export declare function inspectTeamDirectoryConformance(directory: TeamDirectory): TeamDirectoryConformanceReport;

export declare function inspectTransportConformance(fixture: TransportConformanceFixture): Promise<TransportConformanceReport>;

export type JsonRpcTransportConformanceFixture = FixtureFor<"json-rpc", JsonRpcTransportConformanceObservation>;

export type JsonRpcTransportConformanceObservation = TransportConformanceSharedObservation & Readonly<{
    kind: "json-rpc";
    requests: readonly JsonRpcRequestObservation[];
    responses: readonly JsonRpcResponseObservation[];
    notifications: readonly JsonRpcNotificationObservation[];
}>;

export interface KanbanConformanceCheck {
    name: string;
    ok: boolean;
    detail?: string;
}

export interface KanbanConformanceReport {
    ok: boolean;
    checks: KanbanConformanceCheck[];
}

export type RawGatewayConformanceFactory = () => RawGatewayConformanceFixture | Promise<RawGatewayConformanceFixture>;

export type RawGatewayConformanceFixture = Readonly<{
    channel: RawGatewayChannel;
    descriptor: RuntimeControlExtensionDescriptor<RawGatewayChannel>;
    response: unknown;
    ordinaryOperationId: string;
    ordinaryError: unknown;
    unsupportedOperationId: string;
    emitEvent: (event: RawGatewayEvent) => void;
    emitState: (state: RawGatewayConnectionState) => void;
    disposalCount: () => number;
    connectCount: () => number;
    /** Optional rejection identity used to prove rejected disposal is still cached exact-once. */
    expectedDisposalError?: unknown;
}>;

export type RawGatewayConformanceReport = Readonly<{
    valid: boolean;
    failures: readonly string[];
}>;

/** Exercise the provider-neutral raw gateway contract without selecting a provider. */
export declare function runRawGatewayConformance(createChannel: RawGatewayConformanceFactory): Promise<RawGatewayConformanceReport>;

export declare function runRuntimeControlClientConformance(harness: RuntimeControlClientConformanceHarness): Promise<RuntimeControlClientConformanceReport>;

export declare function runRuntimeControlScenarios(environment: RuntimeControlScenarioEnvironment): Promise<RuntimeControlScenarioReport>;

export declare const RUNTIME_CONTROL_CLIENT_MODULES: readonly [
    "authStatus",
    "sessions",
    "models",
    "usage",
    "tasks",
    "workspace",
    "events"
];

export declare const RUNTIME_CONTROL_CLIENT_OPERATION_CAPABILITIES: {
    readonly "authStatus.listAuthStatus": "controlPlane.authStatus.list";
    readonly "sessions.listSessions": "controlPlane.sessions.list";
    readonly "sessions.getSession": "controlPlane.sessions.get";
    readonly "sessions.cancelSession": "controlPlane.sessions.cancel";
    readonly "models.listModels": "controlPlane.models.list";
    readonly "usage.getUsage": "controlPlane.usage.get";
    readonly "tasks.listTasks": "controlPlane.tasks.list";
    readonly "tasks.getTask": "controlPlane.tasks.get";
    readonly "tasks.cancelTask": "controlPlane.tasks.cancel";
    readonly "workspace.listWorkspaces": "controlPlane.workspace.list";
    readonly "workspace.getWorkspace": "controlPlane.workspace.get";
    readonly "events.subscribe": "controlPlane.events.subscribe";
};

export declare const RUNTIME_CONTROL_SCENARIO_EXTENSION: RuntimeControlExtensionDescriptor<RuntimeControlScenarioExtension>;

export declare const RUNTIME_CONTROL_SCENARIOS: readonly RuntimeControlScenarioDefinition[];

export type RuntimeControlClientConformanceHarness = Readonly<{
    /** Provider id every CapabilityUnavailable rejection must identify. */
    providerId: string;
    /** Creates the control plane to exercise. */
    create: () => RuntimeControlClient | Promise<RuntimeControlClient>;
    /** Sensitive values that must never appear in provider errors. */
    secrets?: readonly string[];
    /** Optional provider-backed lifecycle probes for abort and resource ownership. */
    lifecycle?: Readonly<{
        abortReason?: unknown;
        preAbort?: (signal: AbortSignal) => Promise<unknown>;
        inFlightAbort?: (signal: AbortSignal) => Promise<Readonly<{
            operation: Promise<unknown>;
            cleanup?: () => void | Promise<void>;
        }>>;
        ownership?: Readonly<{
            borrowed?: () => Promise<RuntimeControlClientResourceProbe>;
            owned?: () => Promise<RuntimeControlClientResourceProbe>;
        }>;
    }>;
}>;

export type RuntimeControlClientConformanceReport = Readonly<{
    valid: boolean;
    modules: readonly (typeof RUNTIME_CONTROL_CLIENT_MODULES)[number][];
    supported: readonly RuntimeControlClientOperation[];
    unavailable: readonly RuntimeControlClientOperation[];
    failures: readonly string[];
}>;

export type RuntimeControlClientOperation = keyof typeof RUNTIME_CONTROL_CLIENT_OPERATION_CAPABILITIES;

export type RuntimeControlClientResourceProbe = Readonly<{
    dispose: () => void | Promise<void>;
    releases: () => number;
}>;

export type RuntimeControlDisposableResource = Readonly<{
    cleanup: () => void | Promise<void>;
}>;

export type RuntimeControlScenarioDefinition = Readonly<{
    id: string;
    capability: string;
    mutation?: boolean;
}>;

export type RuntimeControlScenarioEnvironment = Readonly<{
    createClient: () => RuntimeControlClient | Promise<RuntimeControlClient>;
    mutationMode: "read-only" | "disposable";
    createResourcePrefix: () => string;
}>;

export type RuntimeControlScenarioExtension = Readonly<{
    createDisposableResources(prefix: string): readonly RuntimeControlDisposableResource[] | Promise<readonly RuntimeControlDisposableResource[]>;
}>;

export type RuntimeControlScenarioReport = Readonly<{
    scenarios: readonly RuntimeControlScenarioResult[];
    failures: readonly string[];
}>;

export type RuntimeControlScenarioResult = Readonly<{
    id: string;
    status: RuntimeControlScenarioStatus;
    capability: string;
    durationMs: number;
    detail?: string;
}>;

export type RuntimeControlScenarioStatus = "passed" | "unavailable" | "failed" | "skipped";

export type RuntimeProviderConformanceCheck = {
    id: string;
    status: "pass" | "fail" | "skip";
    message: string;
};

export type RuntimeProviderConformanceFixture = {
    module: RuntimeProviderModule;
    clientOptions: RuntimeClientOptions;
    /**
     * Required when the client exposes `getRun` and/or `cancelRun`.
     * Also pass `omit` explicitly when methods are intentionally absent.
     */
    runLifecycleSemantics?: RuntimeRunLifecycleSemantics;
};

export type RuntimeProviderConformanceReport = {
    providerKind: string;
    valid: boolean;
    checks: readonly RuntimeProviderConformanceCheck[];
};

/**
 * Declared getRun/cancelRun semantics for conformance fixtures.
 *
 * - `omit` — neither method is present
 * - `server` — real backend get/cancel (methods required)
 * - `sync-store` — SynchronousRunStore degrade (methods required; foreign
 *   getRun must not throw and should return status `"unknown"`)
 * - `unsupported-throw` — methods may be present and throw EndpointNotFound
 */
export type RuntimeRunLifecycleSemantics = "omit" | "server" | "sync-store" | "unsupported-throw";

export type SseTransportConformanceFixture = FixtureFor<"sse", SseTransportConformanceObservation>;

export type SseTransportConformanceObservation = TransportConformanceSharedObservation & Readonly<{
    kind: "sse";
    connections: readonly SseConnectionObservation[];
    deliveredIds: readonly string[];
}>;

export type StdioTransportConformanceFixture = FixtureFor<"stdio", StdioTransportConformanceObservation>;

export type StdioTransportConformanceObservation = ByteTransportConformanceObservation<"stdio">;

export interface TeamDirectoryConformanceCheck {
    name: string;
    ok: boolean;
    detail?: string;
}

export interface TeamDirectoryConformanceReport {
    ok: boolean;
    checks: TeamDirectoryConformanceCheck[];
}

export type TransportConformanceFixture = HttpTransportConformanceFixture | SseTransportConformanceFixture | WebSocketTransportConformanceFixture | JsonRpcTransportConformanceFixture | StdioTransportConformanceFixture | UnixTransportConformanceFixture;

export type TransportConformanceIssue = Readonly<{
    code: "abort_leak" | "unbounded_retry" | "mutation_replayed" | "secret_exposed" | "resource_leak" | "protocol_mismatch";
    message: string;
}>;

export type TransportConformanceReport = Readonly<{
    ok: boolean;
    kind: TransportKind;
    issues: readonly TransportConformanceIssue[];
}>;

export type TransportConformanceSharedObservation = Readonly<{
    maxAttempts: number;
    emissionsAfterAbort: number;
    serializedErrors: readonly string[];
    serializedEvents: readonly string[];
    openResources: number;
}>;

export type TransportKind = "http" | "sse" | "websocket" | "json-rpc" | "stdio" | "unix";

export type UnixTransportConformanceFixture = FixtureFor<"unix", UnixTransportConformanceObservation>;

export type UnixTransportConformanceObservation = ByteTransportConformanceObservation<"unix">;

/** Return a list of human-readable errors for a card that violates the contract. */
export declare function validateKanbanCard(card: KanbanCard): string[];

/** Return human-readable errors for a team that violates the canonical shape. */
export declare function validateTeam(team: Team): string[];

export type WebSocketTransportConformanceFixture = FixtureFor<"websocket", WebSocketTransportConformanceObservation>;

export type WebSocketTransportConformanceObservation = TransportConformanceSharedObservation & Readonly<{
    kind: "websocket";
    lifecycle: readonly WebSocketLifecycleObservation[];
}>;