import type { ReleaseRef } from "../../ailf-shared/index.d.ts";
/**
 * The terminal outcome we can observe for an applied recommendation.
 *
 * v1 is `"submitted"`-only: the Apply path runs the Agent Actions transform
 * asynchronously, so the only thing observed is the gateway's 201 *accept* — a
 * transform that fails server-side after that accept is unobservable today. A
 * completion poll that could distinguish `"succeeded"` / `"failed"` is a
 * deferred follow-up (apply-loop-closure design, decision D5). The union is
 * intentionally a singleton now and widens later without a breaking change.
 */
export type RecommendationApplicationOutcome = "submitted";
/**
 * A durable record that a diagnosis recommendation was applied to a report —
 * the "store the event" half of the close-the-loop hybrid model
 * (docs/design-docs/apply-loop-closure.md §2).
 *
 * It is the first *mutable*, additive sibling of the immutable `ailf.report`
 * event: reports are never edited, so the application fact is captured
 * separately in the same `ailf-prod-private` dataset. Introducing a mutable type
 * into the immutable-reports world is recorded as its own decision.
 *
 * Publish state is deliberately NOT stored here — a release's active/published
 * status is mutable live state an editor changes later in Studio, derived on
 * read from `system.release` (W-applied-recommendation-display), never cached.
 *
 * Carries a canonical D0063 {@link ReleaseRef} (not a bare release-name string)
 * so tracking, surfacing, and re-evaluation all consume the one locator
 * substrate — no parallel release plumbing.
 */
export interface RecommendationApplication {
    /**
     * The report the recommendation belongs to — the dashboard's report handle
     * (its Sanity `_id`, falling back to the human `reportId`). The join key the
     * "Applied" surfacing queries by.
     */
    reportId: string;
    /**
     * Stable, content-derived recommendation identity
     * (`hash(docSlug + "\n" + title)`), minted at apply time. Survives reordering
     * of the diagnosis suggestions; a title rewrite is treated as a new
     * recommendation.
     */
    recommendationKey: string;
    /** Doc slug the recommendation targets. */
    docSlug: string;
    /** Section heading the recommendation narrows to, when present. */
    sectionHeading?: string;
    /** Published document id the Agent Actions transform edited. */
    targetDocumentId: string;
    /** The per-report content release the fix was staged into (D0063). */
    release: ReleaseRef;
    /** Identity that applied it — the App SDK user's email. */
    appliedBy: string;
    /** ISO 8601 UTC timestamp of the apply. */
    appliedAt: string;
    /** Observed outcome — `"submitted"` for v1 (see {@link RecommendationApplicationOutcome}). */
    outcome: RecommendationApplicationOutcome;
}
