/**
 * The Annotation type.
 *
 * Implements `wiki/SharedContracts.md` §1 (vocabulary), §2.1 (resolutionStatus)
 * and `wiki/ArchitectureOverview.md` §4.4. Annotations are the *technical*
 * mark on a document range — meaning and commentary live on EvidenceItem.
 */

import type { AnnotationId, DocumentId, RepresentationId } from "./ids";
import type { Selector } from "./selector";

/** Closed enum per `wiki/SharedContracts.md` §2.1. */
export type AnnotationResolutionStatus =
  | "resolved"
  | "ambiguous"
  | "unresolved"
  | "stale";

export interface Annotation {
  readonly id: AnnotationId;
  readonly documentId: DocumentId;
  readonly representationId?: RepresentationId;
  /**
   * All available selectors for this passage, in order of expected
   * resolution confidence. Per the §3 redundancy rule, the system stores
   * every selector kind it could derive at capture time.
   */
  readonly selectors: readonly Selector[];
  /** Verbatim canonical text at capture time. */
  readonly quote?: string;
  /** Short human note attached to the technical mark. */
  readonly note?: string;
  /**
   * Version of `normalize()` that was active when these selectors were
   * stored. Recorded so future normalization changes can be detected as a
   * migration concern. See `src/shared/text/normalize.ts`.
   */
  readonly normalizeVersion: number;
  readonly resolutionStatus?: AnnotationResolutionStatus;
  readonly createdBy?: string;
  /** ISO-8601 timestamp. */
  readonly createdAt: string;
  /** ISO-8601 timestamp. */
  readonly updatedAt: string;
}