/**
 * InteractionRecord — universal unit for the unified interaction store.
 *
 * Every system event (dispatch, RPC, federation hop, inference, tool call,
 * message, state change, lifecycle) is normalized into this shape before
 * being written to the store.
 *
 * See: ARCHITECTURE/ARCHITECTURE-OBSERVABILITY-PIPELINE-V2.md §3
 */

// ── Record Kind ──────────────────────────────────────────────────────────────

/**
 * Classification of what happened. Determines which fields are meaningful
 * and which retention policy applies.
 */
export type RecordKind =
  | 'message'       // Chat message (user/assistant/tool)
  | 'tool-call'     // Tool invocation (start + end phases)
  | 'inference'     // LLM inference round
  | 'dispatch'      // Actor message delivery
  | 'rpc'           // RequestReply call
  | 'federation'    // Cross-root hop
  | 'lifecycle'     // Actor start/stop/crash/restart
  | 'state'         // State change (setState, CESK checkpoint, blackboard mutation)
  | 'system';       // Framework-level (retention, migration, etc.)

/**
 * Phase within a record's lifecycle. Start/end pairs enable duration
 * computation. Terminal phases indicate the operation is complete.
 */
export type RecordPhase =
  | 'start'
  | 'end'
  | 'error'
  | 'cancelled';

/**
 * Delivery mechanism. Orthogonal to kind (which describes semantics).
 */
export type RecordChannel =
  | 'inbox'     // Direct message to actor $inbox
  | 'events'    // Published on $events topic
  | 'reply';    // RPC reply via $replies correlation

// ── InteractionRecord ────────────────────────────────────────────────────────

export interface InteractionRecord {
  // ── Identity ──
  /** Auto-increment primary key (assigned by store). */
  id?: number;

  // ── Correlation Keys ──
  /** Root trace ID — one per user interaction, never changes. */
  traceId?: string;
  /** Span ID — one per operation (dispatch, RPC call, etc.). */
  spanId?: string;
  /** Parent span ID — links child span to parent for tree reconstruction. */
  parentSpanId?: string;
  /** Session ID — conversation thread. */
  sessionId?: string;
  /** Browser/session resume ID when distinct from the persisted agent session. */
  resumeId?: string;
  /** Request ID — one oracle loop (prompt → response). */
  requestId?: string;
  /** Correlation ID — RPC request/response pair. */
  correlationId?: string;
  /** Session group — multi-agent collaboration key. */
  sessionGroup?: string;
  /** Principal that initiated the interaction when available. */
  principalId?: string;

  // ── Location ──
  /** Source actor mount path (dot-separated). */
  source: string;
  /** Source actor type (e.g., 'AgentActor', 'SystemLlm'). */
  sourceType?: string;
  /** Root where the record was produced. */
  root?: string;
  /** Base root (tab suffix stripped) for cross-tab queries. */
  baseRoot?: string;
  /** Target actor mount path (for dispatches, tool calls). */
  target?: string;
  /** Target root (for cross-root operations). */
  targetRoot?: string;

  // ── Classification ──
  /** What happened. */
  kind: RecordKind;
  /** Phase within the operation lifecycle. */
  phase?: RecordPhase;

  // ── Timing ──
  /** Unix epoch ms when the record was created. */
  ts: number;
  /** Duration in ms (for completed operations). */
  durationMs?: number;

  // ── Delivery ──
  /** How the message was delivered. */
  channel?: RecordChannel;

  // ── Hierarchy ──
  /** Tree depth derived from dot count in source. */
  depth?: number;

  // ── Content ──
  /** Operation name (e.g., '$prompt', 'ts.rename', 'evaluate_lisp'). */
  op?: string;
  /** Message role (for kind='message'). */
  role?: 'user' | 'assistant' | 'tool';
  /** Text content (message text, error message, response text). */
  text?: string;
  /** Structured payload (tool args/result, state patch, etc.). */
  data?: unknown;
  /** Searchable tags. */
  tags?: string[];
  /** State version for CAS and temporal ordering. */
  stateVersion?: number;
  /** Sequence number within a request (for ordering). */
  seq?: number;
  /** Model ID for inference/assistant records. */
  modelId?: string;
  /** Human-readable summary. */
  summary?: string;
  /** Log level (for kind='system'). */
  level?: 'debug' | 'info' | 'warn' | 'error';
}

// ── Service Key ──────────────────────────────────────────────────────────────

/**
 * Symbol key for registering the record store in the service registry.
 * Usage: context.setService(RECORD_STORE_KEY, store)
 */
export const RECORD_STORE_KEY = Symbol.for('matrix.record.store');
