/**
 * RuntimePresenceTypes — shared types for namespace-scoped runtime discovery.
 *
 * These types define the contract between runtimes that announce their presence
 * and consumers (Director, system.runtimes, monitoring) that discover them.
 *
 * See: ARCHITECTURE/ARCHITECTURE-NAMESPACE-DISCOVERY-AND-RUNTIME-PRESENCE.md
 */

import type { HealthSnapshotV1 } from './service-registry.js';
import type { RuntimeInventoryPlacementMetadata } from './placement.js';

/** What kind of claim a runtime makes on a namespace prefix. */
export type RuntimeClaimKind = 'authoritative' | 'proxy' | 'mirror' | 'local-only' | 'pool-member';

/** How a runtime exposes its actor inventory. */
export type RuntimeInventoryMode = 'embedded' | 'pull';

/** Known runtime types. */
export type RuntimeType = 'daemon' | 'browser' | 'cell' | 'container' | 'leaf' | 'worker' | 'folder';

/** Runtime presence events published on the namespace-scoped presence stream. */
export type RuntimePresenceEventV1 = 'announce' | 'heartbeat' | 'departed';

/** A single actor/component entry in a runtime's inventory. */
export interface RuntimeInventoryEntryV1 {
  /** Mount path within the namespace (e.g., 'system.agents', 'explorer'). */
  mount: string;
  /** Actor/component type name (e.g., '_AgentsRoot', 'DirectorTree'). */
  type?: string;
  /** What surface this actor provides. */
  surface?: 'headless' | 'dom' | 'webapp';
  /** Which runtime hosts this actor. */
  runtimeId: string;
  /** What kind of claim this actor represents. */
  claimKind: RuntimeClaimKind;
  /** Placement and callability metadata for this actor. */
  placement?: RuntimeInventoryPlacementMetadata;
  /** Human-readable description. */
  description?: string;
}

/** Full presence record for a runtime in a namespace. */
export interface RuntimePresenceRecordV1 {
  version: '1';

  /** The namespace this runtime participates in. */
  namespaceRoot: string;

  /** Unique identity for this runtime instance. */
  runtimeId: string;

  /** What kind of runtime this is. */
  runtimeType: RuntimeType;

  /** The NATS transport root this runtime uses. */
  runtimeRoot: string;

  /** Optional: authority root for deployment/ownership plane. */
  authorityRoot?: string;

  /** Optional: platform root for HiveCast/hosting plane. */
  platformRoot?: string;

  /** Optional: human-readable application name. */
  app?: string;

  /** What namespace prefixes this runtime claims to serve. */
  claims: Array<{
    prefix: string;
    kind: RuntimeClaimKind;
  }>;

  /** How this runtime exposes its inventory. */
  inventoryMode: RuntimeInventoryMode;

  /** Inline actor list (when inventoryMode === 'embedded'). */
  inventory?: RuntimeInventoryEntryV1[];

  /** Mount path of a catalog actor (when inventoryMode === 'pull'). */
  catalogMount?: string;

  /** Optional: mount path for runtime lifecycle control. */
  controlMount?: string;

  /** Milliseconds before missing heartbeat means runtime is dead. 0 = no timeout. */
  heartbeatTtlMs: number;

  /** When this runtime first registered/announced. */
  registeredAt: number;

  /** Last heartbeat timestamp. */
  lastHeartbeat: number;

  /** Latest health snapshot from the runtime root actor. */
  health?: HealthSnapshotV1;

  /** Optional runtime-specific metadata. */
  metadata?: Record<string, unknown>;
}