// src/engine/core/ILispEnvironment.ts

import type { ILispSecurityContextLike } from './ILispSecurityContextLike';

/**
 * LISP environment interface for dual dispatch.
 *
 * Allows components to have LISP handlers alongside TypeScript handlers.
 * The actor loop checks LISP first, then falls back to TypeScript.
 *
 * This enables:
 * - Hot-reloadable LISP handlers
 * - Homoiconic component definitions
 * - Mixed TS/LISP components
 *
 * Security enforcement per Vision 18 and 27:
 * - Security context flows through invoke() to evaluator
 * - Primitive-level checks happen in the interpreter
 */
export interface ILispEnvironment {
  /**
   * Check if a LISP handler exists for this command.
   * @param mount - Component mount path
   * @param command - Command name (e.g., 'increment')
   */
  hasHandler(mount: string, command: string): boolean;

  /**
   * Invoke a LISP handler.
   * @param mount - Component mount path
   * @param command - Command name
   * @param payload - Message payload
   * @param meta - Message metadata with optional security context
   * @returns Handler result (if any)
   */
  invoke(
    mount: string,
    command: string,
    payload: unknown,
    meta: { ts: number; topic?: string; securityContext?: ILispSecurityContextLike }
  ): Promise<unknown>;

  /**
   * Register a LISP handler for a component.
   * @param mount - Component mount path
   * @param command - Command name
   * @param handler - LISP expression (as string or S-expression)
   */
  registerHandler(mount: string, command: string, handler: unknown): void;

  /**
   * Unregister all handlers for a component (on dispose).
   * @param mount - Component mount path
   */
  unregisterComponent(mount: string): void;
}
