// Types for restore-asset.js — WRITTEN rather than `@ts-expect-error`'d, on retire-asset.d.ts's
// criterion (#748 PR-B): 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 `ref` is a NAMED OPTION, not a positional
// string, and that `site` is a RESOLVED RECORD rather than a key: under `any`,
// `restoreAsset(s, deps, rel, "HEAD~1")` compiles and silently ignores the third argument (options
// is an object, a bare string has no `.ref`), producing the DEFAULT ref instead of the one the
// caller typed.

export interface RestoreAssetOptions {
  /** A sha from list_history. Omitted ⇒ the commit right before HEAD, so a file `retire_asset` just
   *  removed comes back with no ref to look up. */
  ref?: string | null;
  /** The human instruction that asked for this, in the caller's own words — folded into the commit
   *  as a `Reef-Prompt:` trailer (withProvenance, editor.js). */
  prompt?: string | null;
  /** AX-444: run every check without writing. Default false. */
  dryRun?: boolean;
}

/** Take one file back INTO the site's media library, from a past commit. Refuses a path outside the
 *  assets dir, a ref this file was not at, and a site with no earlier commit to restore from
 *  (default ref only). A no-op (HEAD already holds these exact bytes) is an outcome, not an error. */
export function restoreAsset(
  site: unknown,
  deps: { store: Record<string, unknown>; loadCore?: () => Promise<unknown> },
  relPath: string,
  opts?: RestoreAssetOptions,
): Promise<Record<string, unknown>>;