// src/engine/core/IComponentDescriptor.ts

/**
 * Instantiation mode determines behavior when creating a component at an existing mount.
 *
 * Vision 21 Pillar 6 (Lifecycle) - SSOT for instantiation modes.
 *
 * Joe Armstrong (Erlang): "Process registration prevents zombie processes"
 * Don Box (Essential COM): "Instancing mode determines how many can run"
 */
export type InstantiationMode =
  | 'create_new'      // Create at mount, or {mount}.{uuid} if exists (ORPHAN RISK!)
  | 'reuse_existing'  // Return existing if mount occupied (DEFAULT for bridges)
  | 'singleton'       // Fail if already exists
  | 'replace'         // Kill existing, create new (explicit cleanup)
  | 'create_unique';  // Always create at {mount}.{uuid}

/**
 * Component descriptor for runtime.createChild().
 */
export interface IComponentDescriptor {
  /** Component class constructor */
  componentClass: new () => unknown;
  /** Initial properties */
  props?: Record<string, unknown>;

  /**
   * Instantiation mode - what to do if mount already exists.
   *
   * Vision 21 Pillar 6: Lifecycle
   *
   * | Mode            | Mount Exists? | Behavior                              |
   * |-----------------|---------------|---------------------------------------|
   * | create_new      | No            | Create at mount                       |
   * |                 | Yes           | Create at {mount}.{uuid} (ORPHAN!)    |
   * | reuse_existing  | No            | Create at mount                       |
   * |                 | Yes           | Return existing (NO NEW INSTANCE)     |
   * | singleton       | No            | Create at mount                       |
   * |                 | Yes           | ERROR: "Already exists"               |
   * | replace         | No            | Create at mount                       |
   * |                 | Yes           | Destroy existing, create new          |
   * | create_unique   | N/A           | Always create at {mount}.{uuid}       |
   *
   * @default 'create_new' (legacy behavior, but 'reuse_existing' recommended for bridges)
   */
  instantiation?: InstantiationMode;
}
