import { HookOptions } from './common';
/**
 * Spawns a hook execution against an existing workflow job. The hook runs
 * in an isolated dimensional thread within the target job's namespace,
 * allowing it to read/write the same job state without interfering with
 * the main workflow thread.
 *
 * This is the low-level primitive behind `execHook()`. Use `hook()`
 * directly when you need fire-and-forget hook execution or when you
 * manage signal coordination yourself.
 *
 * ## Target Resolution
 *
 * - If `taskQueue` and `workflowName` (or `entity`) are provided, the
 *   hook targets that specific workflow type.
 * - If neither is provided, the hook targets the **current** workflow.
 *   However, targeting the same topic as the current workflow is
 *   rejected to prevent infinite loops.
 *
 * ## Idempotency
 *
 * The `isSideEffectAllowed` guard ensures hooks fire exactly once —
 * on replay, the hook is not re-spawned.
 *
 * ## Examples
 *
 * ```typescript
 * import { Durable } from '@hotmeshio/hotmesh';
 *
 * // Fire-and-forget: spawn a hook without waiting for its result
 * export async function notifyWorkflow(userId: string): Promise<void> {
 *   await Durable.workflow.hook({
 *     taskQueue: 'notifications',
 *     workflowName: 'sendNotification',
 *     args: [userId, 'Your order has shipped'],
 *   });
 *   // Continues immediately, does not wait for the hook
 * }
 * ```
 *
 * ```typescript
 * // Manual signal coordination (equivalent to execHook)
 * export async function manualHookPattern(itemId: string): Promise<string> {
 *   const signalId = `process-${itemId}`;
 *
 *   await Durable.workflow.hook({
 *     taskQueue: 'processors',
 *     workflowName: 'processItem',
 *     args: [itemId, signalId],
 *   });
 *
 *   // Manually wait for the hook to signal back
 *   return await Durable.workflow.condition<string>(signalId);
 * }
 * ```
 *
 * ```typescript
 * // Hook with retry configuration
 * await Durable.workflow.hook({
 *   taskQueue: 'enrichment',
 *   workflowName: 'enrichProfile',
 *   args: [profileId],
 *   config: {
 *     maximumAttempts: 5,
 *     backoffCoefficient: 2,
 *     maximumInterval: '1m',
 *   },
 * });
 * ```
 *
 * @param {HookOptions} options - Hook configuration including target workflow and arguments.
 * @returns {Promise<string>} The resulting hook/stream ID.
 */
export declare function hook(options: HookOptions): Promise<string>;