export type AwaitNotificationError =
  | AwaitNotificationTimeoutError
  | AwaitNotificationClosedError;

/**
 * Stream-based one-shot waiter. Consumes `client.subscribeTo(def)` via
 * `Stream.runHead`, failing with a tagged error on timeout or stream
 * exhaustion. Replaces the deleted `client.waitForNotification(def)` shape
 * at integration-test call sites; preserves the `yield* …` ergonomic but
 * runs entirely on the new `Stream.async`-backed subscription API.
 */
export function awaitOneNotification<D extends AnyNotificationDefinition>(
  client: Pick<ServerTestClient, "subscribeTo">,
  definition: D,
  timeoutMs: number = DEFAULT_AWAIT_NOTIFICATION_TIMEOUT_MS,
): Effect.Effect<
  DecodedNotification<D>,
  AwaitNotificationError | TransportClosedError
> {
  return client.subscribeTo(definition).pipe(
    Stream.runHead,
    Effect.timeoutFail({
      duration: Duration.millis(timeoutMs),
      onTimeout: () =>
        new AwaitNotificationTimeoutError({
          definition: definition.name,
          durationMs: timeoutMs,
        }),
    }),
    Effect.flatMap(
      Option.match({
        onNone: () =>
          Effect.fail(
            new AwaitNotificationClosedError({
              definition: definition.name,
            }),
          ),
        onSome: (notification) => Effect.succeed(notification),
      }),
    ),
  );
}

export function awaitOneNotification<D extends AnyNotificationDefinition>(
  client: Pick<ServerTestClient, "subscribeTo">,
  definition: D,
  timeoutMs: number = DEFAULT_AWAIT_NOTIFICATION_TIMEOUT_MS,
): Effect.Effect<
  DecodedNotification<D>,
  AwaitNotificationError | TransportClosedError
>

export function closeAllClients(): Effect.Effect<void, never>

export interface ConnectedAgent {
  client: ServerTestClient;
  agentId: ProtocolAgentId;
  apiKey: string;
  name: string;
}

export function connectTestClient(opts: {
  agentId: string;
  apiKey: string;
  wsUrl?: string;
  autoConnect?: boolean;
}): Effect.Effect<ServerTestClient, Error>

export type CoreSchemaSqlLoadError =
  | CoreSchemaSqlAccessError
  | CoreSchemaSqlReadError;

const __dirname = dirname(fileURLToPath(import.meta.url));

export interface CoreTestRuntimeServerHandle {
  awaitAgentReady(
    agentId: string,
    timeoutMs: number,
  ): Effect.Effect<CoreTestReadyOutcome, never, never>;
}

export interface CoreTestServer {
  baseUrl: string;
  wsUrl: string;
  db: EffectKysely<Database>;
  coreApp: CoreApp;

  /**
   * Pre-wired `RuntimeServerHandle` for runtime-adapter tests. Implements
   * `awaitAgentReady` by polling the live `ConnectionManager` — the same
   * pattern `@moltzap/runtimes`'s `awaitAgentReadyByPolling` exports for
   * downstream in-process consumers. Out-of-process consumers (zapbot's
   * orchestrator) construct their own handle over WebSocket presence.
   */
  runtimeServer: CoreTestRuntimeServerHandle;

  /**
   * The auto-wired `InMemorySpanExporter`, or `null` when the caller
   * supplied a custom `spanProcessor`. Tests that want to inspect OTel
   * spans call `getFinishedSpans()` on this exporter and map them via
   * their own shim (see `runtimes/` for arena's mapping).
   */
  readonly spanExporter: InMemorySpanExporter | null;
}

export const expectRpcFailure = <A, R>(
  effect: Effect.Effect<A, RpcTestError, R>,
  expectedCode: number,
): Effect.Effect<RpcResponseError, never, R>

export function getBaseUrl(): string

export function getCoreApp(): CoreApp

export function getCoreDb(): EffectKysely<Database>

export function getCoreEncryptionEnvelope(): EnvelopeEncryption

export function getWsUrl(): string

export function loadCoreSchemaSql(): Effect.Effect<
  string,
  CoreSchemaSqlLoadError
>

export const makeFakeService = <S extends object>(impl: Partial<S>): S

export function makePgliteHarness(): Effect.Effect<
  PgliteHarness,
  PgliteHarnessError
>

export const PGLITE_HOOK_TIMEOUT_MS = 30_000

export interface PgliteHarness {
  /** Effect-Kysely-wrapped client. Yieldable as Effect via the toolkit. */
  readonly db: EffectKysely<Database>;

  /**
   * Run raw SQL. The harness uses this to load the schema; tests can use it
   * to seed extra rows after `make()` returns.
   */
  readonly exec: (sql: string) => Effect.Effect<unknown, PgliteExecError>;

  /** Tear down the in-memory instance. Call from `afterEach`. */
  readonly close: Effect.Effect<void, PgliteCloseError>;
}

export type PgliteHarnessError =
  | CoreSchemaSqlLoadError
  | PgliteCreateError
  | PgliteExecError
  | PgliteCloseError;

const SQL_PREVIEW_MAX_CHARS = 160;

function sqlPreview(sql: string): string {
  return sql.replace(/\s+/g, " ").trim().slice(0, SQL_PREVIEW_MAX_CHARS);
}

export function postJson(
  baseUrl: string,
  path: string,
  body: Record<string, unknown>,
): Effect.Effect<PostJsonResult, PostJsonError>

export function registerAgent(
  baseUrl: string,
  name: string,
  opts?: { description?: string; inviteCode?: string },
): Effect.Effect<TestAgent, Error>

export function registerAndConnect(
  name: string,
): Effect.Effect<ConnectedAgent, Error>

export function registerOnly(name: string): Effect.Effect<
  {
    client: ServerTestClient;
    agentId: string;
    apiKey: string;
    claimToken: string | undefined;
  },
  Error
>

export function resetCoreTestDb()

export interface ServerTestClient extends Omit<CloseableTestClient, "close"> {
  close(): Effect.Effect<void, never>;
  subscribeTo<D extends AnyNotificationDefinition>(
    definition: D,
  ): Stream.Stream<DecodedNotification<D>, TransportClosedError>;
}

export function setupAgentGroup(
  count: number,
  opts?: { groupName?: string },
): Effect.Effect<
  {
    agents: ConnectedAgent[];
    conversationId?: ConversationId;
    taskId?: TaskId;
  },
  Error
>

export function setupAgentPair(): Effect.Effect<
  { alice: ConnectedAgent; bob: ConnectedAgent },
  Error
>

export function startCoreTestServer(opts: StartCoreTestServerOptions = {})

export function stopCoreTestServer()

export function trackClient(client: ServerTestClient): void