Skip to content

A full-featured download manager.

66.7 KB
Raw Blame
// src/core/plugin/host/quick-js-worker.ts
// Runs INSIDE a worker_thread. Main thread spawns this file (compiled to
// .cjs) via `new Worker(path)`, then sends a BridgeInitMessage. The worker
// boots a QuickJS VM, evaluates the plugin bundle, and routes capability
// calls back to the host through postMessage.
//
// Lifecycle:
//   parentPort.on('message') awaits init →
//   newQuickJSWASMModuleFromVariant() loads the release-sync WASM →
//   setupGlobals(vm) — install setTimeout / clearTimeout with caps →
//   injectPluginApi(vm, init) — populate globalThis.__motrix_plugin_api__ →
//   vm.evalCode(bundle, ..., { type: 'module' }) — bundle was pre-transformed
//   host-side so `import { x } from 'motrix:plugin-api'` becomes
//   `const { x } = globalThis.__motrix_plugin_api__` (CapabilityBridge does
//   the regex rewrite; see Task 11).
//   On success: send `{type:'ready'}`. On failure: send `{type:'fatal', ...}`.
//
// Capability proxies call assertEffectfulAllowed before bridging, while Hook
// context mutation and metadata staging stay synchronous inside the Worker.
// A versioned, validated Hook exit transfers those effects to the Host as one
// deterministic unit.

import { parentPort } from 'node:worker_threads'
import releaseSyncVariant from '@jitl/quickjs-wasmfile-release-sync'
import {
  CapabilityResponseMessageSchema,
  type CommandInvocationScopeV1,
  HOOK_SCHEMA_VERSION,
  HookAbortMessageSchema,
  HookContextPatchSchema,
  type HookEffectsV1,
  HookEffectsV1Schema,
  HookEnterMessageSchema,
  type HookEnterMessageV1,
  type HookInvocationScopeV1,
  HookMetadataOperationSchema,
} from '@shared/schemas/plugin-hooks'
import {
  newQuickJSWASMModuleFromVariant,
  type QuickJSContext,
  type QuickJSHandle,
} from 'quickjs-emscripten-core'
import { classify } from '../capabilities/classification'
import {
  BridgeExecuteCommandSchema,
  type BridgeInitMessage,
  HOOK_NAMES,
  type HookName,
  type HostToWorker,
  type WorkerToHost,
} from './bridge-protocol'

if (!parentPort) {
  throw new Error('QuickJSWorker must be spawned via worker_threads')
}

const port = parentPort
const pendingCalls = new Map<
  number,
  {
    scope: GuestCallbackScope
    resolve: (value: unknown) => void
    reject: (error: Error & { code?: string }) => void
  }
>()
let nextCallId = 1
// Locale dictionaries are mutated by 'localeChange' events after boot.
// They are declared module-scoped so the i18n.t closure inside the VM
// always sees the latest snapshot.
// fallbackDict is the canonical en-US dict and never changes on localeChange —
// only currentDict switches to the user's language; the fallback stays fixed.
let currentDict: Record<string, string> = {}
let fallbackDict: Record<string, string> = {}
let currentLanguage = ''
let currentDirection: 'ltr' | 'rtl' = 'ltr'

// I18: phase gate — effectful calls are forbidden during activation.
let currentPhase: 'activation' | 'hook' | 'idle' = 'activation'
let violationFatal: { code: string; message: string } | null = null

// Registered hook handlers (stored as duplicated QuickJS handles).
// Populated by hooks.beforeCreate / beforeFinalize / afterComplete / onError
// during activation. The hook execution path uses these on hookEnter events.
const registeredHooks = new Map<string, QuickJSHandle>()

// Registered command handlers (stored as duplicated QuickJS handles).
// Populated by commands.register(id, fn) during activation.
const registeredOperations = new Map<string, QuickJSHandle>()
const operationSignals = new Map<string, QuickJSHandle>()
const registeredCommands = new Map<string, QuickJSHandle>()

// Registered lifecycle.onDeactivate handlers.
// Note: handle cleanup for these collections at shutdown is deferred to Task 23
// / process exit; the worker terminates via process.exit(0) so the OS reclaims
// all memory without an explicit dispose pass.
const registeredDeactivateHandlers: QuickJSHandle[] = []

interface ActiveHookInvocation {
  readonly scope: HookInvocationScopeV1
  readonly hook: HookName
  readonly signalHandle: QuickJSHandle
  readonly abortListeners: QuickJSHandle[]
  readonly effects: HookEffectsV1
  aborted: boolean
  abortReason: string
}

let activeHookInvocation: ActiveHookInvocation | null = null
interface GuestCallbackScope {
  hook: HookInvocationScopeV1 | null
  command: CommandInvocationScopeV1 | null
}

let guestCallbackScope: GuestCallbackScope | null = null

function send(msg: WorkerToHost): void {
  port.postMessage(msg)
}

function assertEffectfulAllowed(capability: string, method: string): void {
  if (currentPhase !== 'activation') return
  if (classify(capability, method) !== 'effectful') return
  violationFatal = {
    code: 'plugin.lifecycle.activation_capability_violation',
    message: `effectful call ${capability}.${method} during activation`,
  }
  send({
    type: 'fatal',
    code: violationFatal.code,
    message: violationFatal.message,
  })
  throw new Error(violationFatal.message)
}

/**
 * Native Host promises settle on Node's microtask queue, outside QuickJS.
 * Bind the first continuation that re-enters QuickJS to the immutable Hook
 * scope captured when the capability call was created. QuickJS drains every
 * guest continuation synchronously from that callback, so a promise retained
 * by Hook A can never resume unscoped or borrow Hook B's active context.
 */
class InvocationScopedPromise<T> extends Promise<T> {
  static get [Symbol.species](): PromiseConstructor {
    return Promise
  }

  constructor(
    executor: ConstructorParameters<typeof Promise<T>>[0],
    private readonly invocationScope: GuestCallbackScope
  ) {
    super(executor)
  }

  // biome-ignore lint/suspicious/noThenProperty: this Promise subclass intentionally scopes its continuation.
  override then<TResult1 = T, TResult2 = never>(
    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null
  ): Promise<TResult1 | TResult2> {
    return super.then(
      onfulfilled
        ? (value) =>
            withGuestCallbackScope(this.invocationScope, () =>
              onfulfilled(value)
            )
        : undefined,
      onrejected
        ? (reason) =>
            withGuestCallbackScope(this.invocationScope, () =>
              onrejected(reason)
            )
        : undefined
    )
  }
}

function callHost(
  capability: string,
  method: string,
  args: unknown[]
): Promise<unknown> {
  if (activeHookInvocation?.aborted) {
    throw codedError('plugin.hook.aborted', activeHookInvocation.abortReason)
  }
  const id = nextCallId++
  const scope = guestCallbackScope ?? {
    hook: activeHookInvocation?.scope ?? null,
    command: null,
  }
  return new InvocationScopedPromise((resolve, reject) => {
    pendingCalls.set(id, { scope, resolve, reject })
    const base = { type: 'call' as const, id, capability, method, args }
    if (scope.hook && scope.command) {
      send({ ...base, ...scope.hook, commandScope: scope.command })
    } else if (scope.hook) {
      send({ ...base, ...scope.hook })
    } else if (scope.command) {
      send({ ...base, commandScope: scope.command })
    } else {
      send(base)
    }
  }, scope)
}

// --- Top-level message dispatcher ---------------------------------------
// Registered synchronously at module load so we don't lose the init
// message that the host sends right after `new Worker(...)`. Node buffers
// messages until the first listener attaches; attaching this synchronously
// guarantees the init message is delivered.

let resolveInit: ((msg: BridgeInitMessage) => void) | null = null
const initPromise = new Promise<BridgeInitMessage>((resolve) => {
  resolveInit = resolve
})

// vmRef holds the QuickJS context after boot so the hookEnter handler can
// invoke registered hooks. Set in boot() after VM creation.
let vmRef: QuickJSContext | null = null
let pluginApiInjected = false

function syncVmLocaleProperties(): void {
  const vm = vmRef
  // A locale event can arrive while QuickJS is booting. In that window the
  // module-scoped snapshot above is already safe to update, but the global API
  // object does not exist yet. injectPluginApi reads the latest module values,
  // so defer handle mutation until the API has been installed.
  if (!vm || !pluginApiInjected) return
  const api = vm.getProp(vm.global, '__motrix_plugin_api__')
  const i18n = vm.getProp(api, 'i18n')
  const app = vm.getProp(api, 'app')
  const language = vm.newString(currentLanguage)
  const direction = vm.newString(currentDirection)
  vm.setProp(i18n, 'language', language)
  vm.setProp(i18n, 'dir', direction)
  vm.setProp(app, 'locale', language)
  direction.dispose()
  language.dispose()
  app.dispose()
  i18n.dispose()
  api.dispose()
}

port.on('message', (msg: HostToWorker) => {
  switch (msg.type) {
    case 'init':
      if (resolveInit) {
        const r = resolveInit
        resolveInit = null
        r(msg)
      }
      return
    case 'response': {
      const parsed = CapabilityResponseMessageSchema.safeParse(msg)
      const pending = pendingCalls.get(msg.id)
      if (!parsed.success) {
        if (pending) {
          pendingCalls.delete(msg.id)
          pending.reject(
            codedError(
              'plugin.hook.concurrent_protocol_violation',
              'invalid capability response message'
            )
          )
        }
        return
      }
      if (pending) {
        pendingCalls.delete(msg.id)
        const responseHookScope = hookScopeFromResponse(parsed.data)
        const responseCommandScope = commandScopeFromMessage(parsed.data)
        if (
          !optionalHookScopeMatches(responseHookScope, pending.scope.hook) ||
          !optionalCommandScopeMatches(
            responseCommandScope,
            pending.scope.command
          )
        ) {
          pending.reject(
            codedError(
              'plugin.hook.concurrent_protocol_violation',
              'capability response belongs to another invocation'
            )
          )
        } else if (parsed.data.ok) {
          pending.resolve(parsed.data.result)
        } else {
          pending.reject(
            codedError(parsed.data.error.code, parsed.data.error.message)
          )
        }
      }
      return
    }
    case 'event':
      if (msg.event === 'shutdown') {
        process.exit(0)
      } else if (msg.event === 'localeChange') {
        currentLanguage = msg.lang
        currentDirection = msg.dir
        currentDict = { ...msg.dict }
        syncVmLocaleProperties()
      } else if (msg.event === 'hookEnter') {
        const parsed = HookEnterMessageSchema.safeParse(msg)
        if (!parsed.success) {
          send({
            type: 'fatal',
            code: 'plugin.hook.input_invalid',
            message: 'Host sent an invalid Hook enter message',
          })
          return
        }
        handleHookEnter(parsed.data)
      } else if (msg.event === 'abort') {
        const parsed = HookAbortMessageSchema.safeParse(msg)
        if (parsed.success) handleHookAbort(parsed.data)
      } else if (msg.event === 'operationAbort') {
        const vm = vmRef
        const signal = operationSignals.get(msg.jobId)
        if (vm && signal) {
          const abort = vm.getProp(signal, '__abort')
          const result = vm.callFunction(abort, signal)
          if (result.error) result.error.dispose()
          else result.value.dispose()
          abort.dispose()
        }
      } else if (msg.event === 'executeCommand') {
        const parsed = BridgeExecuteCommandSchema.safeParse(msg)
        if (parsed.success) handleExecuteCommand(parsed.data)
      } else if (msg.event === 'deactivate') {
        handleDeactivate()
      }
      return
  }
})

// --- hookEnter handler --------------------------------------------------

function handleHookEnter(message: HookEnterMessageV1): void {
  const vm = vmRef
  if (!vm) {
    sendHookFailure(
      message,
      'plugin.runtime.not_ready',
      'plugin runtime is not ready'
    )
    return
  }
  if (activeHookInvocation) {
    sendHookFailure(
      message,
      'plugin.hook.concurrent_protocol_violation',
      'another Hook invocation is already active'
    )
    return
  }

  const fnHandle = registeredHooks.get(message.hook)
  if (!fnHandle) {
    sendHookSuccess(message, {
      schemaVersion: HOOK_SCHEMA_VERSION,
      contextPatches: [],
      metadataOperations: [],
    })
    return
  }

  currentPhase = 'hook'
  const signalHandle = vm.newObject()
  const invocation: ActiveHookInvocation = {
    scope: hookScopeFromEnter(message),
    hook: message.hook,
    signalHandle,
    abortListeners: [],
    effects: {
      schemaVersion: HOOK_SCHEMA_VERSION,
      contextPatches: [],
      metadataOperations: [],
    },
    aborted: false,
    abortReason: '',
  }
  activeHookInvocation = invocation

  const ctxHandle = vm.newObject()
  for (const [key, value] of Object.entries(message.ctxPayload)) {
    const valueHandle = jsValueToVmHandle(vm, value)
    vm.setProp(ctxHandle, key, valueHandle)
    valueHandle.dispose()
  }

  const snapshot = structuredClone(message.metadataSnapshot)
  const metadataHandle = vm.newObject()
  const metaGet = vm.newFunction('get', (keyH) => {
    const key = vm.dump(keyH) as string
    return jsValueToVmHandle(vm, snapshot[key])
  })
  vm.setProp(metadataHandle, 'get', metaGet)
  metaGet.dispose()

  const metaHas = vm.newFunction('has', (keyH) => {
    const key = vm.dump(keyH) as string
    return Object.hasOwn(snapshot, key) ? vm.true : vm.false
  })
  vm.setProp(metadataHandle, 'has', metaHas)
  metaHas.dispose()

  const metaGetAll = vm.newFunction('getAll', () =>
    jsValueToVmHandle(vm, snapshot)
  )
  vm.setProp(metadataHandle, 'getAll', metaGetAll)
  metaGetAll.dispose()

  const metaKeys = vm.newFunction('keys', () =>
    jsValueToVmHandle(vm, Object.keys(snapshot))
  )
  vm.setProp(metadataHandle, 'keys', metaKeys)
  metaKeys.dispose()

  if (message.hook === 'beforeCreate' || message.hook === 'beforeFinalize') {
    const metaSet = vm.newFunction('set', (keyH, valueH) => {
      assertInvocationWritable(invocation)
      const operation = HookMetadataOperationSchema.parse({
        op: 'set',
        key: vm.dump(keyH),
        value: valueH === undefined ? undefined : vm.dump(valueH),
      })
      if (operation.op !== 'set') {
        throw codedError(
          'plugin.hook.output_invalid',
          'metadata.set produced an invalid operation'
        )
      }
      snapshot[operation.key] = structuredClone(operation.value)
      invocation.effects.metadataOperations.push(operation)
      return vm.undefined
    })
    vm.setProp(metadataHandle, 'set', metaSet)
    metaSet.dispose()

    const metaDelete = vm.newFunction('delete', (keyH) => {
      assertInvocationWritable(invocation)
      const operation = HookMetadataOperationSchema.parse({
        op: 'delete',
        key: vm.dump(keyH),
      })
      delete snapshot[operation.key]
      invocation.effects.metadataOperations.push(operation)
      return vm.undefined
    })
    vm.setProp(metadataHandle, 'delete', metaDelete)
    metaDelete.dispose()

    const updateFn = vm.newFunction('update', (patchH) => {
      assertInvocationWritable(invocation)
      const patch = HookContextPatchSchema.parse(
        patchH === undefined ? undefined : vm.dump(patchH)
      )
      invocation.effects.contextPatches.push(structuredClone(patch))
      return vm.undefined
    })
    vm.setProp(ctxHandle, 'update', updateFn)
    updateFn.dispose()
  }

  vm.setProp(ctxHandle, 'metadata', metadataHandle)
  metadataHandle.dispose()

  installAbortSignal(vm, invocation)
  vm.setProp(ctxHandle, 'signal', invocation.signalHandle)

  const callResult = vm.callFunction(fnHandle, vm.undefined, ctxHandle)
  ctxHandle.dispose()

  if (callResult.error) {
    const error = vm.dump(callResult.error)
    callResult.error.dispose()
    finishHookFailure(invocation, vmErrorCode(error), vmErrorMessage(error))
    return
  }

  const maybePromise = callResult.value
  const resolved = vm.resolvePromise(maybePromise)
  maybePromise.dispose()

  resolved.then((settled) => {
    vm.runtime.executePendingJobs()
    if (settled.error) {
      const error = vm.dump(settled.error)
      settled.error.dispose()
      finishHookFailure(invocation, vmErrorCode(error), vmErrorMessage(error))
    } else {
      settled.value.dispose()
      if (invocation.aborted) {
        finishHookFailure(
          invocation,
          'plugin.hook.aborted',
          invocation.abortReason
        )
      } else {
        finishHookSuccess(invocation)
      }
    }
  })
  vm.runtime.executePendingJobs()
}

function installAbortSignal(
  vm: QuickJSContext,
  invocation: ActiveHookInvocation
): void {
  vm.setProp(invocation.signalHandle, 'aborted', vm.false)
  vm.setProp(invocation.signalHandle, 'reason', vm.undefined)
  vm.setProp(invocation.signalHandle, 'onabort', vm.null)

  const addEventListener = vm.newFunction(
    'addEventListener',
    (typeHandle, listenerHandle) => {
      if (activeHookInvocation !== invocation) return vm.undefined
      if (
        vm.dump(typeHandle) !== 'abort' ||
        vm.typeof(listenerHandle) !== 'function'
      ) {
        return vm.undefined
      }
      if (
        !invocation.abortListeners.some((listener) =>
          vmSameValue(vm, listener, listenerHandle)
        )
      ) {
        invocation.abortListeners.push(listenerHandle.dup())
      }
      return vm.undefined
    }
  )
  vm.setProp(invocation.signalHandle, 'addEventListener', addEventListener)
  addEventListener.dispose()

  const removeEventListener = vm.newFunction(
    'removeEventListener',
    (typeHandle, listenerHandle) => {
      if (vm.dump(typeHandle) !== 'abort') return vm.undefined
      const index = invocation.abortListeners.findIndex((listener) =>
        vmSameValue(vm, listener, listenerHandle)
      )
      if (index >= 0) {
        invocation.abortListeners[index]?.dispose()
        invocation.abortListeners.splice(index, 1)
      }
      return vm.undefined
    }
  )
  vm.setProp(
    invocation.signalHandle,
    'removeEventListener',
    removeEventListener
  )
  removeEventListener.dispose()
}

function handleHookAbort(
  message: HookInvocationScopeV1 & { reason: string }
): void {
  const vm = vmRef
  const invocation = activeHookInvocation
  if (!vm || !invocation || !sameHookScope(message, invocation.scope)) return
  if (invocation.aborted) return

  invocation.aborted = true
  invocation.abortReason = message.reason || 'plugin hook aborted'
  vm.setProp(invocation.signalHandle, 'aborted', vm.true)
  const reasonHandle = vm.newString(invocation.abortReason)
  vm.setProp(invocation.signalHandle, 'reason', reasonHandle)
  reasonHandle.dispose()

  const eventHandle = vm.newObject()
  const eventType = vm.newString('abort')
  vm.setProp(eventHandle, 'type', eventType)
  eventType.dispose()

  const onabort = vm.getProp(invocation.signalHandle, 'onabort')
  if (vm.typeof(onabort) === 'function') {
    disposeVmCallResult(
      vm.callFunction(onabort, invocation.signalHandle, eventHandle)
    )
  }
  onabort.dispose()
  for (const listener of invocation.abortListeners) {
    disposeVmCallResult(
      vm.callFunction(listener, invocation.signalHandle, eventHandle)
    )
  }
  eventHandle.dispose()
  vm.runtime.executePendingJobs()

  for (const [id, pending] of pendingCalls) {
    if (
      pending.scope.hook &&
      sameHookScope(pending.scope.hook, invocation.scope)
    ) {
      pendingCalls.delete(id)
      pending.reject(codedError('plugin.hook.aborted', invocation.abortReason))
    }
  }
  vm.runtime.executePendingJobs()
}

function finishHookSuccess(invocation: ActiveHookInvocation): void {
  if (activeHookInvocation !== invocation) return
  const parsed = HookEffectsV1Schema.safeParse(invocation.effects)
  if (!parsed.success) {
    finishHookFailure(
      invocation,
      'plugin.hook.output_invalid',
      parsed.error.issues[0]?.message ?? 'invalid Hook effects'
    )
    return
  }
  sendHookSuccess(invocation.scope, parsed.data)
  releaseHookInvocation(invocation)
}

function finishHookFailure(
  invocation: ActiveHookInvocation,
  code: string,
  message: string
): void {
  if (activeHookInvocation !== invocation) return
  sendHookFailure(invocation.scope, code, message)
  releaseHookInvocation(invocation)
}

function releaseHookInvocation(invocation: ActiveHookInvocation): void {
  for (const listener of invocation.abortListeners) listener.dispose()
  invocation.abortListeners.length = 0
  invocation.signalHandle.dispose()
  if (activeHookInvocation === invocation) activeHookInvocation = null
  currentPhase = 'idle'
}

function sendHookSuccess(
  scope: HookInvocationScopeV1,
  effects: HookEffectsV1
): void {
  send({
    type: 'event',
    event: 'hookExit',
    ...scope,
    ok: true,
    effects,
  })
}

function sendHookFailure(
  scope: HookInvocationScopeV1,
  code: string,
  message: string
): void {
  send({
    type: 'event',
    event: 'hookExit',
    ...scope,
    ok: false,
    error: {
      code: code.slice(0, 64) || 'plugin.runtime.fault',
      message: message.slice(0, 4_096),
    },
  })
}

function assertInvocationWritable(invocation: ActiveHookInvocation): void {
  if (activeHookInvocation !== invocation || invocation.aborted) {
    throw codedError(
      'plugin.hook.aborted',
      invocation.abortReason || 'plugin hook is no longer active'
    )
  }
}

// --- executeCommand handler -----------------------------------------------
//
// Invoked when the host sends a BridgeExecuteCommand event. Dispatches to the
// locally registered command handler, awaits the result (including Promises),
// and sends back a BridgeExecuteCommandResult event.
// Used by test-helpers.ts callPlugin and future Plan C command invocations.

function handleExecuteCommand(message: {
  id: number
  commandId: string
  args: unknown
  commandScope: CommandInvocationScopeV1
  operation?: { jobId: string }
}): void {
  const { id, commandId, args, commandScope } = message
  const vm = vmRef
  if (!vm) {
    send({
      type: 'event',
      event: 'executeCommandResult',
      id,
      commandScope,
      ok: false,
      errorCode: 'plugin.runtime.not_ready',
      errorMessage: 'VM not initialised',
    })
    return
  }

  const handler = (
    message.operation ? registeredOperations : registeredCommands
  ).get(commandId)
  if (!handler) {
    send({
      type: 'event',
      event: 'executeCommandResult',
      id,
      commandScope,
      ok: false,
      errorCode: 'plugin.commands.not_found',
      errorMessage: `command not found: ${commandId}`,
    })
    return
  }

  // Temporarily allow effectful calls — the command runs in 'hook'-equivalent phase.
  const prevPhase = currentPhase
  currentPhase = 'hook'

  const argsHandle = jsValueToVmHandle(vm, args)
  const callbackScope: GuestCallbackScope = {
    hook: null,
    command: commandScope,
  }
  const context = message.operation
    ? makeOperationContext(vm, message.operation.jobId)
    : vm.undefined
  const callResult = withGuestCallbackScope(callbackScope, () =>
    vm.callFunction(handler, vm.undefined, argsHandle, context)
  )
  if (message.operation) context.dispose()
  argsHandle.dispose()

  if (callResult.error) {
    const err = vm.dump(callResult.error)
    callResult.error.dispose()
    currentPhase = prevPhase
    const errorCode = vmErrorCode(err)
    const errorMessage = vmErrorMessage(err)
    send({
      type: 'event',
      event: 'executeCommandResult',
      id,
      commandScope,
      ok: false,
      errorCode,
      errorMessage,
    })
    return
  }

  const maybePromise = callResult.value
  const resolved = vm.resolvePromise(maybePromise)
  maybePromise.dispose()

  resolved.then((settled) => {
    withGuestCallbackScope(callbackScope, () => {
      vm.runtime.executePendingJobs()
      currentPhase = prevPhase
      if (settled.error) {
        const err = vm.dump(settled.error)
        settled.error.dispose()
        const errorCode = vmErrorCode(err)
        const errorMessage = vmErrorMessage(err)
        send({
          type: 'event',
          event: 'executeCommandResult',
          id,
          commandScope,
          ok: false,
          errorCode,
          errorMessage,
        })
      } else {
        const result = vm.dump(settled.value)
        settled.value.dispose()
        send({
          type: 'event',
          event: 'executeCommandResult',
          id,
          commandScope,
          ok: true,
          result,
        })
      }
    })
  })
  withGuestCallbackScope(callbackScope, () => vm.runtime.executePendingJobs())
}

// --- handleDeactivate ---------------------------------------------------
//
// Invoked when the host sends a BridgeDeactivate event. Iterates
// registeredDeactivateHandlers, calls each with no args, awaits any returned
// Promise, and sends back BridgeDeactivateComplete{ok}.
// If any handler throws / rejects, sends BridgeDeactivateComplete{ok:false}.
// The host enforces the 2-second total budget via Promise.race on its side;
// the worker makes a best-effort sequential run.

function handleDeactivate(): void {
  const vmSnapshot = vmRef
  if (!vmSnapshot || registeredDeactivateHandlers.length === 0) {
    send({ type: 'event', event: 'deactivateComplete', ok: true })
    return
  }

  // Capture as non-null local so the async inner function can use it safely.
  const vm: QuickJSContext = vmSnapshot

  // Run handlers sequentially, chaining Promises.
  const handlers = registeredDeactivateHandlers.slice()

  async function runHandlers(): Promise<void> {
    for (const fnHandle of handlers) {
      const callResult = vm.callFunction(fnHandle, vm.undefined)
      if (callResult.error) {
        const err = vm.dump(callResult.error)
        callResult.error.dispose()
        const errorCode = vmErrorCode(err)
        throw Object.assign(new Error(String(err)), { code: errorCode })
      }
      const maybePromise = callResult.value
      const resolved = vm.resolvePromise(maybePromise)
      maybePromise.dispose()
      vm.runtime.executePendingJobs()
      const settled = await resolved
      vm.runtime.executePendingJobs()
      if (settled.error) {
        const err = vm.dump(settled.error)
        settled.error.dispose()
        const errorCode = vmErrorCode(err)
        throw Object.assign(new Error(String(err)), { code: errorCode })
      }
      settled.value.dispose()
    }
  }

  runHandlers().then(
    () => {
      send({ type: 'event', event: 'deactivateComplete', ok: true })
    },
    (err: Error & { code?: string }) => {
      send({
        type: 'event',
        event: 'deactivateComplete',
        ok: false,
        errorCode: err.code ?? 'plugin.runtime.fault',
      })
    }
  )
}

// --- Boot ---------------------------------------------------------------

async function boot(): Promise<void> {
  const init = await initPromise
  currentDict = { ...init.i18n.currentDict }
  fallbackDict = { ...init.i18n.fallbackDict }
  currentLanguage = init.i18n.language
  currentDirection = init.i18n.dir

  const QuickJS = await newQuickJSWASMModuleFromVariant(releaseSyncVariant)
  const vm = QuickJS.newContext()
  vmRef = vm
  // Declared outside try so the catch block can call it.
  // Assigned by setupGlobals before any code that could throw; if
  // setupGlobals itself throws there are no timer handles to clean up so the
  // no-op default is safe.
  let cleanupTimers: () => void = () => {}
  try {
    cleanupTimers = setupGlobals(vm)
    injectPluginApi(vm, init)
    const bundleResult = vm.evalCode(init.bundleSource, init.manifest.main, {
      type: 'module',
    })
    if (bundleResult.error) {
      const err = vm.dump(bundleResult.error)
      bundleResult.error.dispose()
      if (!violationFatal) {
        send({
          type: 'fatal',
          code: 'plugin.bundle.parse_error',
          message: typeof err === 'string' ? err : JSON.stringify(err),
        })
      }
      cleanupTimers()
      vm.dispose()
      return
    }
    bundleResult.value.dispose()
    send({ type: 'ready' })
    currentPhase = 'idle'
  } catch (e) {
    send({
      type: 'fatal',
      code: 'plugin.runtime.boot_failed',
      message: (e as Error).message,
    })
    cleanupTimers()
    vm.dispose()
  }
}

// --- Globals (timers) ---------------------------------------------------

function setupGlobals(vm: QuickJSContext): () => void {
  installUrlGlobals(vm)

  // setTimeout / setInterval enforce caps:
  //   - MAX_ACTIVE: hard cap on simultaneously-scheduled timers per plugin
  //   - MAX_DELAY:  clamps absurdly large delays to 30s
  // When the active cap is exceeded we throw an Error from inside the
  // newFunction callback — quickjs-emscripten converts that to a VM-level
  // exception so the plugin sees a thrown error rather than a silent no-op.
  const timers = new Map<number, NodeJS.Timeout>()
  const intervalCallbacks = new Map<number, ReturnType<typeof setInterval>>()
  const intervalHandleRefs = new Map<number, () => void>()
  let nextId = 1
  const MAX_DELAY = 30_000
  const MAX_ACTIVE = 100
  const reportTimerActivity = () => {
    // Kept outside WorkerToHost on purpose: this Host lifecycle signal is
    // consumed directly by PluginHost and never enters CapabilityBridge's
    // request/response protocol.
    port.postMessage({
      type: 'timer_activity',
      activeCount: timers.size + intervalCallbacks.size,
    })
  }

  const setTimeoutFn = vm.newFunction('setTimeout', (cbHandle, delayHandle) => {
    if (timers.size >= MAX_ACTIVE) {
      throw new Error('timer_quota_exceeded')
    }
    const delay = Math.min(vm.getNumber(delayHandle), MAX_DELAY)
    const id = nextId++
    const callbackScope = guestCallbackScope ?? {
      hook: activeHookInvocation?.scope ?? null,
      command: null,
    }
    // Persistent handle survives the synchronous callback return; we
    // dispose it when the timer fires (one-shot) or is cleared.
    const persistent = cbHandle.dup()
    timers.set(
      id,
      setTimeout(() => {
        timers.delete(id)
        reportTimerActivity()
        withGuestCallbackScope(callbackScope, () => {
          const res = vm.callFunction(persistent, vm.undefined)
          persistent.dispose()
          disposeVmCallResult(res)
          vm.runtime.executePendingJobs()
        })
      }, delay)
    )
    reportTimerActivity()
    return vm.newNumber(id)
  })
  vm.setProp(vm.global, 'setTimeout', setTimeoutFn)
  setTimeoutFn.dispose()

  const clearTimeoutFn = vm.newFunction('clearTimeout', (idHandle) => {
    const id = vm.getNumber(idHandle)
    const t = timers.get(id)
    if (t) {
      clearTimeout(t)
      timers.delete(id)
      reportTimerActivity()
    }
    return vm.undefined
  })
  vm.setProp(vm.global, 'clearTimeout', clearTimeoutFn)
  clearTimeoutFn.dispose()

  const setIntervalFn = vm.newFunction(
    'setInterval',
    (cbHandle, delayHandle) => {
      if (timers.size + intervalCallbacks.size >= MAX_ACTIVE) {
        throw new Error('timer_quota_exceeded')
      }
      const delay = Math.min(vm.getNumber(delayHandle), MAX_DELAY)
      const id = nextId++
      const callbackScope = guestCallbackScope ?? {
        hook: activeHookInvocation?.scope ?? null,
        command: null,
      }
      const persistent = cbHandle.dup()
      const interval = setInterval(() => {
        withGuestCallbackScope(callbackScope, () => {
          const res = vm.callFunction(persistent, vm.undefined)
          disposeVmCallResult(res)
          vm.runtime.executePendingJobs()
        })
      }, delay)
      intervalCallbacks.set(id, interval)
      intervalHandleRefs.set(id, () => persistent.dispose())
      reportTimerActivity()
      return vm.newNumber(id)
    }
  )
  vm.setProp(vm.global, 'setInterval', setIntervalFn)
  setIntervalFn.dispose()

  const clearIntervalFn = vm.newFunction('clearInterval', (idHandle) => {
    const id = vm.getNumber(idHandle)
    const interval = intervalCallbacks.get(id)
    if (interval) {
      clearInterval(interval)
      intervalCallbacks.delete(id)
      const release = intervalHandleRefs.get(id)
      if (release) {
        release()
        intervalHandleRefs.delete(id)
      }
      reportTimerActivity()
    }
    return vm.undefined
  })
  vm.setProp(vm.global, 'clearInterval', clearIntervalFn)
  clearIntervalFn.dispose()

  // Returns a cleanup function that drains all active timer handles before
  // the VM is disposed. Must not throw — it is called from error paths where
  // a secondary exception would mask the original error.
  return () => {
    try {
      for (const [, interval] of intervalCallbacks) {
        clearInterval(interval)
      }
      intervalCallbacks.clear()
      for (const [, release] of intervalHandleRefs) {
        release()
      }
      intervalHandleRefs.clear()
      for (const [, t] of timers) {
        clearTimeout(t)
      }
      timers.clear()
      reportTimerActivity()
    } catch {
      // Swallow — cleanup must not throw from error paths
    }
  }
}

const URL_STRING_FIELDS = [
  'href',
  'protocol',
  'origin',
  'host',
  'hostname',
  'port',
  'pathname',
  'search',
  'hash',
  'username',
  'password',
] as const

/**
 * QuickJS does not ship WHATWG URL globals. Parse with Node's standards-based
 * implementation and copy only string fields/functions into guest-owned VM
 * objects; no Node object, dispatcher, or Host capability crosses the realm.
 */
function installUrlGlobals(vm: QuickJSContext): void {
  const urlConstructor = vm.newFunction('URL', (inputHandle, baseHandle) => {
    const input = String(vm.dump(inputHandle))
    const base =
      baseHandle === undefined ? undefined : String(vm.dump(baseHandle))
    const parsed = new URL(input, base)
    const object = vm.newObject()
    const syncFields = () => {
      for (const field of URL_STRING_FIELDS) {
        const value = vm.newString(parsed[field])
        vm.setProp(object, field, value)
        value.dispose()
      }
    }
    syncFields()

    const searchParams = makeUrlSearchParamsHandle(
      vm,
      new URLSearchParams(parsed.searchParams),
      (serialized) => {
        parsed.search = serialized
      }
    )
    vm.setProp(object, 'searchParams', searchParams)
    searchParams.dispose()

    for (const method of ['toString', 'toJSON'] as const) {
      const fn = vm.newFunction(method, () => vm.newString(parsed.href))
      vm.setProp(object, method, fn)
      fn.dispose()
    }
    return object
  })
  const canParse = vm.newFunction('canParse', (inputHandle, baseHandle) => {
    const input = String(vm.dump(inputHandle))
    const base =
      baseHandle === undefined ? undefined : String(vm.dump(baseHandle))
    return URL.canParse(input, base) ? vm.true : vm.false
  })
  vm.setProp(vm.global, '__motrixCreateURL', urlConstructor)
  urlConstructor.dispose()
  vm.setProp(vm.global, '__motrixCanParseURL', canParse)
  canParse.dispose()

  const searchParamsConstructor = vm.newFunction(
    'URLSearchParams',
    (initHandle) =>
      makeUrlSearchParamsHandle(vm, urlSearchParamsFromVm(vm, initHandle))
  )
  vm.setProp(
    vm.global,
    '__motrixCreateURLSearchParams',
    searchParamsConstructor
  )
  searchParamsConstructor.dispose()

  const constructors = vm.evalCode(`
    (() => {
      const createURL = globalThis.__motrixCreateURL
      const canParseURL = globalThis.__motrixCanParseURL
      const createURLSearchParams = globalThis.__motrixCreateURLSearchParams
      delete globalThis.__motrixCreateURL
      delete globalThis.__motrixCanParseURL
      delete globalThis.__motrixCreateURLSearchParams
      globalThis.URL = class URL {
        constructor(input, base) {
          return createURL(String(input), base === undefined ? undefined : String(base))
        }
        static canParse(input, base) {
          return canParseURL(String(input), base === undefined ? undefined : String(base))
        }
      }
      globalThis.URLSearchParams = class URLSearchParams {
        constructor(init) {
          return createURLSearchParams(init)
        }
      }
    })()
  `)
  if (constructors.error) {
    const error = vm.dump(constructors.error)
    constructors.error.dispose()
    throw new Error(`failed to install URL globals: ${vmErrorMessage(error)}`)
  }
  constructors.value.dispose()
}

function urlSearchParamsFromVm(
  vm: QuickJSContext,
  initHandle: QuickJSHandle | undefined
): URLSearchParams {
  if (initHandle === undefined) return new URLSearchParams()
  const init = vm.dump(initHandle)
  if (typeof init === 'string') return new URLSearchParams(init)
  if (Array.isArray(init)) {
    const pairs = init.map((entry) => {
      if (!Array.isArray(entry) || entry.length !== 2) {
        throw new TypeError('URLSearchParams tuple entries must have length 2')
      }
      return [String(entry[0]), String(entry[1])] as [string, string]
    })
    return new URLSearchParams(pairs)
  }
  if (init && typeof init === 'object') {
    return new URLSearchParams(
      Object.fromEntries(
        Object.entries(init as Record<string, unknown>).map(([key, value]) => [
          key,
          String(value),
        ])
      )
    )
  }
  return new URLSearchParams(String(init))
}

function makeUrlSearchParamsHandle(
  vm: QuickJSContext,
  params: URLSearchParams,
  onChange: (serialized: string) => void = () => {}
): QuickJSHandle {
  const object = vm.newObject()
  const mutated = () => onChange(params.toString())

  const append = vm.newFunction('append', (nameHandle, valueHandle) => {
    params.append(String(vm.dump(nameHandle)), String(vm.dump(valueHandle)))
    mutated()
    return vm.undefined
  })
  vm.setProp(object, 'append', append)
  append.dispose()

  const deleteFn = vm.newFunction('delete', (nameHandle, valueHandle) => {
    const name = String(vm.dump(nameHandle))
    if (valueHandle === undefined) params.delete(name)
    else params.delete(name, String(vm.dump(valueHandle)))
    mutated()
    return vm.undefined
  })
  vm.setProp(object, 'delete', deleteFn)
  deleteFn.dispose()

  const get = vm.newFunction('get', (nameHandle) => {
    const value = params.get(String(vm.dump(nameHandle)))
    return value === null ? vm.null : vm.newString(value)
  })
  vm.setProp(object, 'get', get)
  get.dispose()

  const getAll = vm.newFunction('getAll', (nameHandle) =>
    jsValueToVmHandle(vm, params.getAll(String(vm.dump(nameHandle))))
  )
  vm.setProp(object, 'getAll', getAll)
  getAll.dispose()

  const has = vm.newFunction('has', (nameHandle, valueHandle) => {
    const name = String(vm.dump(nameHandle))
    const present =
      valueHandle === undefined
        ? params.has(name)
        : params.has(name, String(vm.dump(valueHandle)))
    return present ? vm.true : vm.false
  })
  vm.setProp(object, 'has', has)
  has.dispose()

  const set = vm.newFunction('set', (nameHandle, valueHandle) => {
    params.set(String(vm.dump(nameHandle)), String(vm.dump(valueHandle)))
    mutated()
    return vm.undefined
  })
  vm.setProp(object, 'set', set)
  set.dispose()

  const sort = vm.newFunction('sort', () => {
    params.sort()
    mutated()
    return vm.undefined
  })
  vm.setProp(object, 'sort', sort)
  sort.dispose()

  const toStringFn = vm.newFunction('toString', () =>
    vm.newString(params.toString())
  )
  vm.setProp(object, 'toString', toStringFn)
  toStringFn.dispose()

  return object
}

// --- Value marshaling ---------------------------------------------------
//
// jsValueToVmHandle: converts a JS value from host into a QuickJS VM handle.
// Supports: string, number, boolean, null, undefined, Array, plain Object.
// Uint8Array: marshaled as a plain Array of numbers (JSON round-trip).
// This is a Task 20 limitation; Plan G will ship proper typed-array marshaling.

function jsValueToVmHandle(vm: QuickJSContext, v: unknown): QuickJSHandle {
  if (v === undefined) return vm.undefined
  if (v === null) return vm.null
  if (typeof v === 'boolean') return v ? vm.true : vm.false
  if (typeof v === 'number') return vm.newNumber(v)
  if (typeof v === 'string') return vm.newString(v)
  if (v instanceof Uint8Array) {
    // Serialize as Array<number>; loses typed-array semantics but safe.
    // TODO(Plan G): proper Uint8Array marshaling via QuickJS typed-array API.
    const arr = vm.newArray()
    for (let i = 0; i < v.length; i++) {
      const n = vm.newNumber(v[i])
      vm.setProp(arr, i, n)
      n.dispose()
    }
    return arr
  }
  if (Array.isArray(v)) {
    const arr = vm.newArray()
    for (let i = 0; i < v.length; i++) {
      const elem = jsValueToVmHandle(vm, v[i])
      vm.setProp(arr, i, elem)
      elem.dispose()
    }
    return arr
  }
  if (typeof v === 'object') {
    const obj = vm.newObject()
    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
      const valH = jsValueToVmHandle(vm, val)
      vm.setProp(obj, k, valH)
      valH.dispose()
    }
    return obj
  }
  // Fallback: stringify
  return vm.newString(String(v))
}

// Extract the `code` field from a dumped VM error value, defaulting to
// 'plugin.runtime.fault'. `err` is the result of vm.dump(handle) — an arbitrary
// JS value the plugin threw. Mirrors the inline ternary that was repeated at
// every hook/command/deactivate error-extraction site.
function vmErrorCode(err: unknown): string {
  return typeof err === 'object' && err !== null && 'code' in err
    ? String((err as { code: unknown }).code)
    : 'plugin.runtime.fault'
}

// Extract the `message` field from a dumped VM error value, falling back to
// String(err) when no message property is present.
function vmErrorMessage(err: unknown): string {
  return typeof err === 'object' && err !== null && 'message' in err
    ? String((err as { message: unknown }).message)
    : String(err)
}

function codedError(code: string, message: string): Error & { code?: string } {
  return Object.assign(new Error(message), { code })
}

function hookScopeFromEnter(
  message: HookEnterMessageV1
): HookInvocationScopeV1 {
  return {
    invocationId: message.invocationId,
    callChainId: message.callChainId,
    permissionGeneration: message.permissionGeneration,
  }
}

function hookScopeFromResponse(message: unknown): HookInvocationScopeV1 | null {
  if (typeof message !== 'object' || message === null) return null
  const candidate = message as Record<string, unknown>
  if (
    typeof candidate.invocationId !== 'string' ||
    typeof candidate.callChainId !== 'string' ||
    typeof candidate.permissionGeneration !== 'number'
  ) {
    return null
  }
  return {
    invocationId: candidate.invocationId,
    callChainId: candidate.callChainId,
    permissionGeneration: candidate.permissionGeneration,
  }
}

function optionalHookScopeMatches(
  left: HookInvocationScopeV1 | null,
  right: HookInvocationScopeV1 | null
): boolean {
  if (!left || !right) return left === right
  return sameHookScope(left, right)
}

function commandScopeFromMessage(
  message: unknown
): CommandInvocationScopeV1 | null {
  if (typeof message !== 'object' || message === null) return null
  const candidate = (message as { commandScope?: unknown }).commandScope
  if (typeof candidate !== 'object' || candidate === null) return null
  const parsed = candidate as CommandInvocationScopeV1
  if (
    !Number.isSafeInteger(parsed.commandInvocationId) ||
    parsed.commandInvocationId <= 0 ||
    typeof parsed.callChain?.id !== 'string' ||
    !Array.isArray(parsed.callChain.plugins)
  ) {
    return null
  }
  return parsed
}

function optionalCommandScopeMatches(
  left: CommandInvocationScopeV1 | null,
  right: CommandInvocationScopeV1 | null
): boolean {
  if (!left || !right) return left === right
  return (
    left.commandInvocationId === right.commandInvocationId &&
    left.callChain.id === right.callChain.id &&
    left.callChain.plugins.length === right.callChain.plugins.length &&
    left.callChain.plugins.every(
      (pluginId, index) => pluginId === right.callChain.plugins[index]
    )
  )
}

function sameHookScope(
  left: HookInvocationScopeV1,
  right: HookInvocationScopeV1
): boolean {
  return (
    left.invocationId === right.invocationId &&
    left.callChainId === right.callChainId &&
    left.permissionGeneration === right.permissionGeneration
  )
}

function withGuestCallbackScope<T>(
  scope: GuestCallbackScope,
  callback: () => T
): T {
  const previous = guestCallbackScope
  guestCallbackScope = scope
  try {
    return callback()
  } finally {
    guestCallbackScope = previous
  }
}

function disposeVmCallResult(
  result: ReturnType<QuickJSContext['callFunction']>
): void {
  if (result.error) result.error.dispose()
  else result.value.dispose()
}

function vmSameValue(
  vm: QuickJSContext,
  left: QuickJSHandle,
  right: QuickJSHandle
): boolean {
  const objectHandle = vm.getProp(vm.global, 'Object')
  const isHandle = vm.getProp(objectHandle, 'is')
  const result = vm.callFunction(isHandle, objectHandle, left, right)
  isHandle.dispose()
  objectHandle.dispose()
  if (result.error) {
    result.error.dispose()
    return false
  }
  const equal = vm.dump(result.value) === true
  result.value.dispose()
  return equal
}

// makeEffectfulNs: builds a QuickJS namespace object for a given capability
// where every listed method is effectful (calls assertEffectfulAllowed then
// callHost, returning a Promise-handle to the plugin).
function makeEffectfulNs(
  vm: QuickJSContext,
  cap: string,
  methods: ReadonlyArray<string>
): QuickJSHandle {
  const ns = vm.newObject()
  for (const m of methods) {
    const f = vm.newFunction(m, (...argHandles: QuickJSHandle[]) => {
      try {
        assertEffectfulAllowed(cap, m)
      } catch {
        // assertEffectfulAllowed already sent fatal; return undefined to abort
        return vm.undefined
      }
      const args = argHandles.map((h) => vm.dump(h))
      const deferred = vm.newPromise()
      callHost(cap, m, args).then(
        (result) => {
          const h = jsValueToVmHandle(vm, result)
          deferred.resolve(h)
          h.dispose()
          vm.runtime.executePendingJobs()
        },
        (err: Error & { code?: string }) => {
          const errH = vm.newError(err.message)
          if (err.code) {
            const codeH = vm.newString(err.code)
            vm.setProp(errH, 'code', codeH)
            codeH.dispose()
          }
          deferred.reject(errH)
          errH.dispose()
          vm.runtime.executePendingJobs()
        }
      )
      deferred.settled.then(() => vm.runtime.executePendingJobs())
      return deferred.handle
    })
    vm.setProp(ns, m, f)
    f.dispose()
  }
  return ns
}

function makeOperationContext(
  vm: QuickJSContext,
  jobId: string
): QuickJSHandle {
  const context = makeEffectfulNs(vm, 'operation', ['progress'])
  const media = makeEffectfulNs(vm, 'operation', ['probe', 'mergeStreams'])
  const files = makeEffectfulNs(vm, 'operation', ['readText', 'writeText'])
  vm.setProp(context, 'media', media)
  media.dispose()
  vm.setProp(context, 'files', files)
  files.dispose()
  const id = vm.newString(jobId)
  vm.setProp(context, 'jobId', id)
  id.dispose()
  const fail = vm.newFunction('fail', (code) => ({
    error: vm.newError(`operation.error.${String(vm.dump(code)).slice(0, 64)}`),
  }))
  vm.setProp(context, 'fail', fail)
  fail.dispose()
  const signal = vm.evalCode(`(() => {
    const listeners = new Set(); let aborted = false;
    return Object.freeze({ get aborted() { return aborted }, get reason() { return aborted ? 'Operation cancelled' : undefined },
      throwIfAborted() { if (aborted) throw new Error('Operation cancelled') },
      addEventListener(type, listener) { if (type === 'abort' && typeof listener === 'function' && listeners.size < 32) listeners.add(listener) },
      removeEventListener(type, listener) { if (type === 'abort') listeners.delete(listener) },
      __abort() { if (aborted) return; aborted = true; for (const listener of listeners) { try { listener({type: 'abort'}) } catch {} } listeners.clear() }
    })
  })()`)
  if (signal.error) {
    signal.error.dispose()
    throw new Error('Cannot create operation signal')
  }
  operationSignals.set(jobId, signal.value)
  vm.setProp(context, 'signal', signal.value)
  return context
}

// --- Plugin API injection ----------------------------------------------

function injectPluginApi(vm: QuickJSContext, init: BridgeInitMessage): void {
  const api = vm.newObject()
  const pluginId = init.pluginId

  // ── log ────────────────────────────────────────────────────────────────
  // EXCEPTION: log.* is classified 'effectful' by the classification table
  // but calling log at top-level is intentionally permitted (the test.echo
  // fixture calls log.info during activation). assertEffectfulAllowed is NOT
  // called for log — this matches the Plan A implementation and keeps the
  // existing e2e test green. All log calls are fire-and-forget.
  const log = vm.newObject()
  for (const level of ['trace', 'debug', 'info', 'warn', 'error', 'fatal']) {
    const f = vm.newFunction(level, (msgH, fieldsH) => {
      const msg = vm.dump(msgH) as string
      const fields =
        fieldsH !== undefined ? (vm.dump(fieldsH) as object) : undefined
      void callHost('log', level, [msg, fields])
      return vm.undefined
    })
    vm.setProp(log, level, f)
    f.dispose()
  }
  vm.setProp(api, 'log', log)
  log.dispose()

  // ── app ────────────────────────────────────────────────────────────────
  // Read-only snapshot from init. Properties, not methods — no bridge calls.
  const app = vm.newObject()
  for (const k of [
    'version',
    'platform',
    'runtime',
    'locale',
    'arch',
  ] as const) {
    const v = vm.newString(k === 'locale' ? currentLanguage : init.app[k])
    vm.setProp(app, k, v)
    v.dispose()
  }
  vm.setProp(api, 'app', app)
  app.dispose()

  // ── i18n ───────────────────────────────────────────────────────────────
  // language / dir and currentDict are updated by localeChange events.
  // t(key, params): reads module-scoped currentDict / fallbackDict, resolving
  // synchronously — no bridge call needed
  //   because the dict was shipped with the init message.
  //   NOTE: classification table lists i18n.t as 'effectful', but it is
  //   resolved locally with no side-effects beyond the dict lookup, so
  //   assertEffectfulAllowed is skipped here too (consistent with Plan A).
  const i18nObj = vm.newObject()
  const langH = vm.newString(currentLanguage)
  vm.setProp(i18nObj, 'language', langH)
  langH.dispose()
  const dirH = vm.newString(currentDirection)
  vm.setProp(i18nObj, 'dir', dirH)
  dirH.dispose()
  const tFn = vm.newFunction('t', (keyH, paramsH) => {
    const key = vm.dump(keyH) as string
    const params =
      paramsH !== undefined
        ? (vm.dump(paramsH) as Record<string, unknown>)
        : undefined
    const tmpl = currentDict[key] ?? fallbackDict[key] ?? key
    const rendered = params
      ? tmpl.replace(/\{\{(\w+)\}\}/g, (_, k) => String(params[k] ?? ''))
      : tmpl
    return vm.newString(rendered)
  })
  vm.setProp(i18nObj, 't', tFn)
  tFn.dispose()
  vm.setProp(api, 'i18n', i18nObj)
  i18nObj.dispose()

  // ── hooks ──────────────────────────────────────────────────────────────
  // Registration-only: stores the fn handle and sends a register event.
  // Calling hooks.X() outside activation is allowed (no rejection),
  // per Task 1 classification: registration-only methods are always permitted.
  const hooks = vm.newObject()
  for (const h of HOOK_NAMES) {
    const hf = vm.newFunction(h, (fnHandle) => {
      // Dispose any previously registered handle for this hook (re-registration)
      const prev = registeredHooks.get(h)
      if (prev) prev.dispose()
      registeredHooks.set(h, fnHandle.dup())
      send({ type: 'register', kind: 'hook', key: h })
      return vm.undefined
    })
    vm.setProp(hooks, h, hf)
    hf.dispose()
  }
  vm.setProp(api, 'hooks', hooks)
  hooks.dispose()

  // ── commands ───────────────────────────────────────────────────────────
  // commands.register(id, fn): registration-only — stores fn locally.
  // commands.execute(id, args): effectful. Self-command calls are rejected
  // before any local handler or Host queue can run; cross-plugin calls bridge
  // through the Host-owned command graph and its immutable call chain.
  const commands = vm.newObject()

  const operationRegister = vm.newFunction('registerOperation', (idH, fnH) => {
    const id = vm.dump(idH) as string
    if (
      !init.manifest.contributes.commands?.some(
        (command) => command.id === id && command.execution === 'operation'
      )
    )
      return { error: vm.newError('Operation command is not declared') }
    registeredOperations.get(id)?.dispose()
    registeredOperations.set(id, fnH.dup())
    send({ type: 'register', kind: 'command', key: id })
    return vm.undefined
  })
  vm.setProp(commands, 'registerOperation', operationRegister)
  operationRegister.dispose()

  const regF = vm.newFunction('register', (idH, fnH) => {
    const id = vm.dump(idH) as string
    const prev = registeredCommands.get(id)
    if (prev) prev.dispose()
    registeredCommands.set(id, fnH.dup())
    send({ type: 'register', kind: 'command', key: id })
    return vm.undefined
  })
  vm.setProp(commands, 'register', regF)
  regF.dispose()

  const execF = vm.newFunction('execute', (idH, argsH) => {
    try {
      assertEffectfulAllowed('commands', 'execute')
    } catch {
      return vm.undefined
    }
    const id = vm.dump(idH) as string
    const args = argsH !== undefined ? vm.dump(argsH) : undefined

    // Self re-entry would deadlock behind this plugin's current lane owner if
    // routed through the Host, and direct local dispatch would bypass the
    // shared lane/call-chain policy. Reject it before either can happen.
    if (id.startsWith(`${pluginId}.`)) {
      const deferred = vm.newPromise()
      const errH = vm.newError('plugin.runtime.reentrant_call')
      const codeH = vm.newString('plugin.runtime.reentrant_call')
      vm.setProp(errH, 'code', codeH)
      codeH.dispose()
      deferred.reject(errH)
      errH.dispose()
      deferred.settled.then(() => vm.runtime.executePendingJobs())
      return deferred.handle
    }

    // Cross-plugin: bridge call.
    const deferred = vm.newPromise()
    callHost('commands', 'execute', [id, args]).then(
      (result) => {
        const h = jsValueToVmHandle(vm, result)
        deferred.resolve(h)
        h.dispose()
        vm.runtime.executePendingJobs()
      },
      (err: Error & { code?: string }) => {
        const errH = vm.newError(err.message)
        if (err.code) {
          const codeH = vm.newString(err.code)
          vm.setProp(errH, 'code', codeH)
          codeH.dispose()
        }
        deferred.reject(errH)
        errH.dispose()
        vm.runtime.executePendingJobs()
      }
    )
    deferred.settled.then(() => vm.runtime.executePendingJobs())
    return deferred.handle
  })
  vm.setProp(commands, 'execute', execF)
  execF.dispose()

  vm.setProp(api, 'commands', commands)
  commands.dispose()

  // ── lifecycle ──────────────────────────────────────────────────────────
  // onDeactivate(fn): registration-only — stores handler locally.
  // onActivate(fn): registration-only — stored but Plan B doesn't fire it.
  // The bridge's dispatchLifecycle also has a stub; the worker side is the
  // canonical storage. Task 23 wires the full deactivation protocol.
  const lifecycle = vm.newObject()

  const onDeactF = vm.newFunction('onDeactivate', (fnH) => {
    registeredDeactivateHandlers.push(fnH.dup())
    send({ type: 'register', kind: 'hook', key: 'onDeactivate' })
    return vm.undefined
  })
  vm.setProp(lifecycle, 'onDeactivate', onDeactF)
  onDeactF.dispose()

  const onActivateF = vm.newFunction('onActivate', (_fnH) => {
    // Store silently; Plan B doesn't fire onActivate but the API surface
    // must not throw so plugins can write `lifecycle.onActivate(() => {})`.
    return vm.undefined
  })
  vm.setProp(lifecycle, 'onActivate', onActivateF)
  onActivateF.dispose()

  vm.setProp(api, 'lifecycle', lifecycle)
  lifecycle.dispose()

  // ── http ───────────────────────────────────────────────────────────────
  // Replaces the minimal Task 2 stub.
  const http = makeEffectfulNs(vm, 'http', ['request', 'get', 'post'])
  vm.setProp(api, 'http', http)
  http.dispose()

  // ── storage ────────────────────────────────────────────────────────────
  const storage = makeEffectfulNs(vm, 'storage', [
    'get',
    'set',
    'compareAndSet',
    'delete',
    'keys',
  ])
  vm.setProp(api, 'storage', storage)
  storage.dispose()

  // ── crypto ─────────────────────────────────────────────────────────────
  const crypto = makeEffectfulNs(vm, 'crypto', [
    'hash',
    'hmac',
    'randomBytes',
    'aes',
  ])
  vm.setProp(api, 'crypto', crypto)
  crypto.dispose()

  // ── config ─────────────────────────────────────────────────────────────
  const config = makeEffectfulNs(vm, 'config', ['get', 'getRaw', 'getAll'])
  vm.setProp(api, 'config', config)
  config.dispose()

  // ── notify ─────────────────────────────────────────────────────────────
  const notify = makeEffectfulNs(vm, 'notify', ['show'])
  vm.setProp(api, 'notify', notify)
  notify.dispose()

  // ── fs.storage ─────────────────────────────────────────────────────────
  const fsStorage = makeEffectfulNs(vm, 'fs.storage', [
    'read',
    'write',
    'delete',
    'rename',
    'exists',
    'stat',
    'mkdir',
  ])
  vm.setProp(api, 'fs.storage', fsStorage)
  fsStorage.dispose()

  // ── fs.task ────────────────────────────────────────────────────────────
  // Methods that require hook context. Bridge enforces hook-context gate.
  // openReader: bridge returns {opened: true} stub for Task 20; Plan C wires
  // actual context. Worker proxy wraps the stub into a plain object.
  // TODO(Plan C): implement streaming reader protocol via opId round-trips.
  // stat, exists, computeHash, rename — effectful via bridge (same plumbing as
  // makeEffectfulNs). openReader is appended below because it needs a bespoke
  // reader-proxy resolve arm.
  const fsTask = makeEffectfulNs(vm, 'fs.task', [
    'stat',
    'exists',
    'computeHash',
    'rename',
  ])

  // openReader: bridge stub for Task 20. Plan C will wire actual context.
  // Returns a stub reader object with no-op read() and close().
  const openReaderF = vm.newFunction('openReader', (optsH) => {
    try {
      assertEffectfulAllowed('fs.task', 'openReader')
    } catch {
      return vm.undefined
    }
    const opts = optsH !== undefined ? vm.dump(optsH) : {}
    const deferred = vm.newPromise()
    callHost('fs.task', 'openReader', [opts]).then(
      () => {
        // Bridge returns {opened: true}. Wrap into a stub reader proxy.
        // TODO(Plan C): bridge will return {opId} once context wiring is done.
        // Worker will wrap opId into a real reader with .read(maxChunkSize)
        // and .close() that round-trip via op calls.
        const readerObj = vm.newObject()
        const readFn = vm.newFunction('read', () => {
          // Stub: resolves immediately with null (no data).
          const p = vm.newPromise()
          const n = vm.null
          p.resolve(n)
          n.dispose()
          p.settled.then(() => vm.runtime.executePendingJobs())
          return p.handle
        })
        vm.setProp(readerObj, 'read', readFn)
        readFn.dispose()
        const closeFn = vm.newFunction('close', () => vm.undefined)
        vm.setProp(readerObj, 'close', closeFn)
        closeFn.dispose()
        deferred.resolve(readerObj)
        readerObj.dispose()
        vm.runtime.executePendingJobs()
      },
      (err: Error & { code?: string }) => {
        const errH = vm.newError(err.message)
        if (err.code) {
          const codeH = vm.newString(err.code)
          vm.setProp(errH, 'code', codeH)
          codeH.dispose()
        }
        deferred.reject(errH)
        errH.dispose()
        vm.runtime.executePendingJobs()
      }
    )
    deferred.settled.then(() => vm.runtime.executePendingJobs())
    return deferred.handle
  })
  vm.setProp(fsTask, 'openReader', openReaderF)
  openReaderF.dispose()

  vm.setProp(api, 'fs.task', fsTask)
  fsTask.dispose()

  // ── ffmpeg ─────────────────────────────────────────────────────────────
  // Launch methods return a handle object in the VM with:
  //   .id       — string opId
  //   .result   — Promise that polls bridge op.result.await(opId)
  //   .abort()  — calls bridge op.abort(opId), fire-and-forget
  //
  // Progress: exposed as .pollProgress() returning a Promise<FfmpegProgress|null>
  // that calls bridge op.progress.pull(opId). An AsyncIterable would be ideal
  // but is complex to implement inside QuickJS; plugins can poll on a timer.
  // TODO(Plan C): upgrade to AsyncIterable progress if needed.
  //
  // probe: returns the result directly (not an op handle).
  const ffmpeg = vm.newObject()
  vm.setProp(ffmpeg, 'available', init.ffmpeg?.available ? vm.true : vm.false)
  if (init.ffmpeg?.version) {
    const version = vm.newString(init.ffmpeg.version)
    vm.setProp(ffmpeg, 'version', version)
    version.dispose()
  }

  function makeFfmpegHandle(opId: string): QuickJSHandle {
    const handleObj = vm.newObject()

    const idH = vm.newString(opId)
    vm.setProp(handleObj, 'id', idH)
    idH.dispose()

    // result: Promise — awaits bridge op.result.await(opId)
    const resultDeferred = vm.newPromise()
    callHost('ffmpeg', 'op.result.await', [opId]).then(
      (res) => {
        const h = jsValueToVmHandle(vm, res)
        resultDeferred.resolve(h)
        h.dispose()
        vm.runtime.executePendingJobs()
      },
      (err: Error & { code?: string }) => {
        const errH = vm.newError(err.message)
        if (err.code) {
          const codeH = vm.newString(err.code)
          vm.setProp(errH, 'code', codeH)
          codeH.dispose()
        }
        resultDeferred.reject(errH)
        errH.dispose()
        vm.runtime.executePendingJobs()
      }
    )
    resultDeferred.settled.then(() => {
      vm.runtime.executePendingJobs()
      resultDeferred.dispose()
    })
    vm.setProp(handleObj, 'result', resultDeferred.handle)
    // Retain the deferred's resolve/reject handles until settlement. The
    // object's reference retains the promise, but cannot settle it by itself.

    // pollProgress(): returns Promise<FfmpegProgress|null>
    const pollFn = vm.newFunction('pollProgress', () => {
      const deferred = vm.newPromise()
      callHost('ffmpeg', 'op.progress.pull', [opId]).then(
        (prog) => {
          const h = jsValueToVmHandle(vm, prog)
          deferred.resolve(h)
          h.dispose()
          vm.runtime.executePendingJobs()
        },
        (err: Error & { code?: string }) => {
          const errH = vm.newError(err.message)
          if (err.code) {
            const codeH = vm.newString(err.code)
            vm.setProp(errH, 'code', codeH)
            codeH.dispose()
          }
          deferred.reject(errH)
          errH.dispose()
          vm.runtime.executePendingJobs()
        }
      )
      deferred.settled.then(() => vm.runtime.executePendingJobs())
      return deferred.handle
    })
    vm.setProp(handleObj, 'pollProgress', pollFn)
    pollFn.dispose()

    // abort(): fire-and-forget
    const abortFn = vm.newFunction('abort', () => {
      void callHost('ffmpeg', 'op.abort', [opId])
      return vm.undefined
    })
    vm.setProp(handleObj, 'abort', abortFn)
    abortFn.dispose()

    return handleObj
  }

  // probe: direct result (not an op handle)
  const probeFn = vm.newFunction('probe', (optsH) => {
    try {
      assertEffectfulAllowed('ffmpeg', 'probe')
    } catch {
      return vm.undefined
    }
    const opts = optsH !== undefined ? vm.dump(optsH) : {}
    const deferred = vm.newPromise()
    callHost('ffmpeg', 'probe', [opts]).then(
      (result) => {
        const h = jsValueToVmHandle(vm, result)
        deferred.resolve(h)
        h.dispose()
        vm.runtime.executePendingJobs()
      },
      (err: Error & { code?: string }) => {
        const errH = vm.newError(err.message)
        if (err.code) {
          const codeH = vm.newString(err.code)
          vm.setProp(errH, 'code', codeH)
          codeH.dispose()
        }
        deferred.reject(errH)
        errH.dispose()
        vm.runtime.executePendingJobs()
      }
    )
    deferred.settled.then(() => vm.runtime.executePendingJobs())
    return deferred.handle
  })
  vm.setProp(ffmpeg, 'probe', probeFn)
  probeFn.dispose()

  // Launch methods: transcode, extractAudio, mergeStreams, generateThumbnail, run
  for (const m of [
    'transcode',
    'extractAudio',
    'mergeStreams',
    'generateThumbnail',
    'run',
  ]) {
    const f = vm.newFunction(m, (optsH) => {
      try {
        assertEffectfulAllowed('ffmpeg', m)
      } catch {
        return vm.undefined
      }
      const opts = optsH !== undefined ? vm.dump(optsH) : {}
      const deferred = vm.newPromise()
      callHost('ffmpeg', m, [opts]).then(
        (result) => {
          const { opId } = result as { opId: string }
          const handle = makeFfmpegHandle(opId)
          deferred.resolve(handle)
          handle.dispose()
          vm.runtime.executePendingJobs()
        },
        (err: Error & { code?: string }) => {
          const errH = vm.newError(err.message)
          if (err.code) {
            const codeH = vm.newString(err.code)
            vm.setProp(errH, 'code', codeH)
            codeH.dispose()
          }
          deferred.reject(errH)
          errH.dispose()
          vm.runtime.executePendingJobs()
        }
      )
      deferred.settled.then(() => vm.runtime.executePendingJobs())
      return deferred.handle
    })
    vm.setProp(ffmpeg, m, f)
    f.dispose()
  }

  vm.setProp(api, 'ffmpeg', ffmpeg)
  ffmpeg.dispose()

  vm.setProp(vm.global, '__motrix_plugin_api__', api)
  pluginApiInjected = true
  api.dispose()
}

boot().catch((e: Error) => {
  send({
    type: 'fatal',
    code: 'plugin.runtime.boot_failed',
    message: e.message,
  })
})