// Types for retire-asset.js — WRITTEN rather than `@ts-expect-error`'d, on retire-site.d.ts's
// criterion: this is our module, the hosted door is a caller, and getting it wrong is
// customer-facing.
//
// 🔴 What a declaration buys HERE specifically is that `site` is a RESOLVED RECORD and not a key,
// and that `force` is a named option rather than a positional boolean: under `any`,
// `retireAsset(s, deps, rel, true)` compiles and silently force-deletes a file the scan refused.

/** Where the built site serves a repo path from — `<assetsDir>/.` is overlaid onto the site root. */
export function assetServedPath(site: { assetsDir?: string }, repoPath: string): string;

/** The same store, read as of one commit: `list` derived from `treeAt`, `read`/`readMany` pinned to
 *  the ref, `listAssets` still answering for today (see the .js header for why). */
export function storeAtRef(store: Record<string, unknown>, site: unknown, ref: string, knownTree?: Map<string, string> | null): Promise<Record<string, unknown>>;

/** #967 point 3 — at or above either one, a call with a background lane runs as a job. */
export const RETIRE_ASYNC_IR_FILES: number;
export const RETIRE_ASYNC_SCAN_MS: number;
export const RETIRE_WAIT_DESC: string;
export const RETIRE_JOB_TIMING: Readonly<{ heartbeatMs: number; staleMs: number; ttlMs: number }>;

/** One reference row: which asset, in what form, where, and in which of the two trees. */
export interface AssetReferenceRow {
  path: string;
  kind: string;
  where: string;
  at: 'draft' | 'published';
  version?: string;
}

/** THE ONE CHECK — the draft and the newest published anchor, filtered to `targets`. */
export function assetRetirementCheck(
  site: unknown,
  deps: { store: Record<string, unknown>; loadCore: () => Promise<unknown> },
  targets: readonly string[],
  tips?: { headSha?: string | null; headTree?: Map<string, string> | null; anchors?: Array<{ name?: string; sha?: string }>; allowSkip?: boolean } | null,
): Promise<{ referencedBy: AssetReferenceRow[]; publishedAnchor: { name?: string; sha?: string } | null; trees: 1 | 2 }>;

/** Take one file out of the site's media library. Refuses while anything still points at it. */
export function retireAsset(
  site: unknown,
  deps: {
    store: Record<string, unknown>;
    loadCore: () => Promise<unknown>;
    retireAssetCache?: { get(key: string): Promise<unknown>; put(key: string, value: unknown): Promise<void> };
    /** #967 point 3 — keeps a background check alive after the answer. Absent ⇒ always synchronous. */
    retireAssetDefer?: (work: Promise<unknown>) => void;
    /** #1136 — hands the job's JSON spec to HostedSiteOperations (alarm custody). Wins over `retireAssetDefer`. */
    retireAssetStartJob?: (spec: Record<string, unknown>) => Promise<void>;
    retireAsyncLimits?: { irFiles: number; scanMs: number };
    retireJobTiming?: { heartbeatMs?: number; staleMs?: number; ttlMs?: number };
  },
  relPath: string,
  opts?: { force?: boolean; dryRun?: boolean; prompt?: string | null; jobId?: string | null; waitMs?: number; background?: boolean; expectMode?: 'dry_run' | 'real' | null },
): Promise<Record<string, unknown>>;

/** A job record's `error`: what a job settles as when nobody runs it any more (#1133's words). */
export interface RetireJobError { message: string; code: string | null; referencedBy?: AssetReferenceRow[]; scan?: unknown }
/** #1142/#1146 — where a real delete's commit stands when a job settles as something other than
 *  `done`: 'scan' (not attempted yet — "nothing was deleted" is true), 'committing' (sent, landing
 *  unknown), 'committed' (durably known to have landed, `finishRetire`'s `onCommitted`, awaited). */
export type RetireJobPhase = 'scan' | 'committing' | 'committed';
/** #1142 — a FUNCTION of `phase`, not a fixed sentence: which of #1133's three phrasings applies
 *  depends on whether a real delete's commit could already have landed. */
export const RETIRE_JOB_LOST: (phase: RetireJobPhase) => RetireJobError;
export function retireJobUnsavedError(rel: string, dryRun: boolean): RetireJobError;
export function retireJobError(e: unknown, phase?: RetireJobPhase): RetireJobError;

/** #1136 — one run of a background job to its answer (the DO's alarm, or the closed lane's waitUntil). */
export function runRetireJob(
  site: { key: string },
  deps: Record<string, unknown>,
  spec: Record<string, unknown> & { jobId: string; rel: string; dryRun: boolean },
  hooks?: { headTree?: Map<string, string> | null; beforeCommit?: (() => Promise<void>) | null },
): Promise<'done' | 'failed' | 'abandoned'>;

/**
 * Settle a job that will not run (again) — only while its record still says `running`. `error` may
 * be a ready-made `RetireJobError` (the caller already knows the phase it applies to) or a function
 * of the record's own phase (#1142 — `RETIRE_JOB_LOST`, or a caller-built closure over `retireJobError`).
 */
export function settleRetireJob(
  site: { key: string },
  cache: { get(key: string): Promise<unknown>; put(key: string, value: unknown): Promise<void> },
  spec: { jobId: string; rel: string; dryRun: boolean } & Record<string, unknown>,
  error: RetireJobError | ((phase: RetireJobPhase) => RetireJobError),
): Promise<'failed' | 'abandoned'>;