/**
 * Field Context — Phase 22A Working Memory snapshot.
 *
 * Captured by `buildFieldContextSnapshot` from the Phase 21 event stream,
 * rendered to markdown by `formatFieldContext`, and injected as a prefix
 * into agent prompts by agent-handlers.
 *
 * See docs/prd/phase-22a-working-memory.md for the full design.
 */

export interface FieldContextWorktree {
  id: string
  name: string
  branchName: string | null
}

export interface FieldContextFocusFile {
  path: string
  name: string
}

export interface FieldContextSelection {
  path: string
  fromLine: number
  toLine: number
  length: number
}

export interface FieldContextTerminalOutput {
  head: string
  tail: string
  truncated: boolean
  exitCode: number | null
}

export interface FieldContextLastTerminal {
  command: string
  commandAt: number
  /** Null if no `terminal.output` event was correlated to the command. */
  output: FieldContextTerminalOutput | null
}

export interface FieldContextActivityEntry {
  timestamp: number
  type: string
  /** One-line human-readable summary. Generated by the builder. */
  summary: string
}

export interface FieldContextSnapshot {
  /** Generation time (ms). Single clock used throughout the pipeline. */
  asOf: number
  /** Window size used when building (ms). */
  windowMs: number
  /** The worktree we built context for; null if the worktree was not found. */
  worktree: FieldContextWorktree | null
  /** User-authored notes from `worktrees.context`. */
  worktreeNotes: string | null
  /**
   * v1.4.1: Pinned Facts — user-authored permanent facts for this worktree.
   * Rendered before semantic memory; null/empty content suppresses the section.
   */
  pinnedFacts: {
    contentMd: string
    updatedAt: number
  } | null
  /**
   * Phase 24C: resumed work-state from the previous session on this worktree.
   * Null when no checkpoint, stale, or field collection disabled.
   */
  checkpoint: ResumedCheckpointBlock | null
  /**
   * Episodic memory (Phase 22B): a longer-horizon rolling summary of this
   * worktree's recent activity. Null if no summary has been compacted yet
   * or if field collection is disabled.
   */
  episodicSummary: {
    markdown: string
    compactorId: string
    compactedAt: number
    sourceEventCount: number
  } | null
  /**
   * Semantic memory (Phase 22C.1): hand-authored markdown files at two layers.
   * Null when user has disabled memory injection.
   */
  semanticMemory: {
    project: SemanticMemoryBlock
    user: SemanticMemoryBlock
  } | null
  /** Aggregated current focus derived from file.* events. */
  focus: {
    file: FieldContextFocusFile | null
    selection: FieldContextSelection | null
  }
  /** Most recent command + correlated output in the window, if any. */
  lastTerminal: FieldContextLastTerminal | null
  /** Remaining events in chronological order, deduped against structured sections. */
  recentActivity: FieldContextActivityEntry[]
}

/**
 * A single memory.md file layer (Phase 22C.1).
 * The path is returned even when the file does not exist,
 * so the debug UI can tell the user where to write one.
 */
export interface SemanticMemoryBlock {
  path: string
  /** Markdown contents; null when the file does not exist. */
  markdown: string | null
}

/**
 * Phase 24C — Resumed Session Checkpoint injection block.
 *
 * Built by `verifyCheckpoint` from the most recent
 * `field_session_checkpoints` row for the worktree. Null when there is no
 * checkpoint, or when the checkpoint is stale (branch changed / ≥50% hot
 * files drifted / expired > 24h).
 *
 * `currentGoal` and `nextAction` are rule-based heuristics; the formatter
 * MUST render them with a "(heuristic)" tag so the agent knows they may be
 * wrong.
 */
export interface ResumedCheckpointBlock {
  createdAt: number
  ageMinutes: number
  source: 'abort' | 'shutdown'
  summary: string
  currentGoal: string | null
  nextAction: string | null
  blockingReason: string | null
  hotFiles: string[]
  warnings: string[]
}
