/**
 * Handler execution — pipeline step 4.
 *
 * Calls the resolved handler's `execute` with a fully assembled
 * `RemoteContext`: validated params, auth context, optional bound self,
 * typed deps, and a kernel `BoundClientSessionView`. The handler may return a
 * value, a Promise, or an async generator (for `output: 'stream'`).
 */

import type { FnMap } from '@astrale-os/kernel-client'
import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
import type { AuthContext } from '@astrale-os/kernel-core'
import type { Defer, Sleep } from '@astrale-os/kernel-server'

import type { FunctionContextApi } from '../auth/function-context.js'
import type { DomainAuthority } from '../auth/issuer-mint.js'
import type { CallerContext, RemoteEnv } from '../method/context.js'
import type { Step } from '../step/index.js'
import type { SelfResult, TypedSelf } from './self.js'

// oxlint-disable-next-line no-explicit-any
type HandlerFn = (...args: any[]) => any

export type ExecuteParams = {
  /** Handler may omit `execute` when authored as a stub (spec-only binding). */
  handler: { execute?: HandlerFn }
  /** Namespaced ref of the dispatched method — names the offending method in the
   *  stub-leak diagnostic below (the dispatcher passes `bound.ref`). */
  ref?: string
  params: Record<string, unknown>
  auth: AuthContext | null
  /** Untyped fallback ({@link withNode}) or the rich typed self ({@link withBoundNode}). */
  self: SelfResult | TypedSelf<unknown> | undefined
  deps: unknown
  env: RemoteEnv
  kernel: BoundClientSessionView<FnMap> | null
  caller?: CallerContext
  /** Mint seam for identities this domain issues. */
  domain: DomainAuthority
  fn: FunctionContextApi
  step: Step
  defer: Defer
  sleep: Sleep
}

export async function executeHandler(ctx: ExecuteParams): Promise<unknown> {
  if (typeof ctx.handler.execute !== 'function') {
    throw new Error(
      `executeHandler: handler${ctx.ref ? ` for "${ctx.ref}"` : ''} has no \`execute\` body — ` +
        `this is a binding stub that should have been resolved to a remote redirect upstream.`,
    )
  }
  return ctx.handler.execute({
    params: ctx.params,
    auth: ctx.auth,
    self: ctx.self,
    deps: ctx.deps,
    env: ctx.env,
    kernel: ctx.kernel,
    ...(ctx.caller !== undefined ? { caller: ctx.caller } : {}),
    domain: ctx.domain,
    fn: ctx.fn,
    step: ctx.step,
    defer: ctx.defer,
    sleep: ctx.sleep,
  })
}