import type { RecommendationStatus } from "../../ailf-shared/index.d.ts";
/**
 * A durable, append-only record that a viewer set a diagnosis recommendation's
 * disposition. One document is appended per change; the current status is the
 * latest event for a recommendation (ordered by the server-assigned
 * `_createdAt`). The full event stream is the audit history.
 *
 * This is the disposition axis. It is deliberately separate from
 * `RecommendationApplication` (the AI-apply action record): a recommendation
 * can be `dismissed` and never applied, or `implemented` by hand with no AI
 * record. The two compose in the UI rather than merging in the data.
 *
 * `actor` is server-inferred at write time from the authenticated principal
 * (not client-supplied), so it cannot be spoofed. `at` is also stamped
 * server-side; ordering uses Content Lake's `_createdAt`, not `at`.
 *
 * @see docs/superpowers/specs/2026-06-16-recommendation-status-events-design.md
 */
export interface RecommendationStatusEvent {
    /** The report the recommendation belongs to (the dashboard's report handle). */
    reportId: string;
    /** Stable content-derived recommendation identity (`hash(docSlug + "\n" + title)`). */
    recommendationKey: string;
    /** Doc slug the recommendation targets — enables the gated docSlug fallback match. */
    docSlug: string;
    /** Section heading the recommendation narrows to, when present. */
    sectionHeading?: string;
    /** The disposition this event set. */
    status: RecommendationStatus;
    /** Optional free-text note, useful on `dismissed`. */
    note?: string;
    /** Server-inferred identity that set it (the gateway principal id). */
    actor: string;
    /** ISO 8601 UTC timestamp, stamped server-side at write. */
    at: string;
}
