/**
 * cache-hit-restore.ts — helpers for the eval cache-hit branch in
 * `RunEvalStep`. Stamps `sourceRunId` onto a cached report's artifact
 * refs so the new run's manifest advertises the cached artifacts via
 * cross-run lineage instead of pointing at GCS objects that were never
 * written under the new runId.
 *
 * @see docs/decisions/D0040-artifact-ref-source-run-id.md
 * @see docs/design-docs/cache-hit-artifact-restoration.md
 */
import { type ArtifactManifest, type RunId } from "../_vendor/ailf-core/index.d.ts";
/**
 * Copy an artifact manifest verbatim and stamp `sourceRunId` on every ref
 * that doesn't already carry one.
 *
 * The ref's `path`, `bucket`, `entries`, `bytes`, `preview`, etc. travel
 * unchanged — they already point at the source run's storage. `sourceRunId`
 * is added so retention/GC and observability tooling can follow the
 * cross-run dependency.
 *
 * **Transitive lineage.** When a cached report's refs already carry a
 * `sourceRunId` (because that report was itself a cache hit), we preserve it.
 * `opts.sourceRunId` is only the *immediate* cache parent; if the cached
 * report's refs already point at the ultimate source run, blindly overwriting
 * would drop the lineage one hop per cache propagation and 404 readers that
 * trust `sourceRunId` for path reconstruction.
 *
 * Invariant maintained across any number of cache hops: every ref's
 * `sourceRunId` equals the runId encoded in its `path` (= where the bytes
 * physically live).
 *
 * **Post-hoc artifacts are dropped.** Refs whose descriptor has
 * `writePolicy: "post-hoc"` (e.g. `diagnosis`) are skipped: the cached
 * report's slot points at the *previous* run's path, but the post-hoc
 * producer fires again on the new run and emits a fresh ref anchored at
 * the new runId. Injecting the cached cross-run ref into the accumulator
 * makes `FinalizeRunStep` embed the stale path into the on-GCS
 * `runs/<newRunId>/manifest.json`; the post-hoc emit then only patches the
 * Sanity report doc, leaving the GCS manifest stale. Dropping the ref
 * here keeps the GCS manifest consistent with the cache-miss shape (no
 * post-hoc slot until the post-hoc emit lands), and the reader-side
 * fallback resolves diagnosis via the Sanity doc, which the post-hoc
 * patch keeps correct.
 *
 * Pure function; safe to call without side effects.
 */
export declare function remapToCacheHitRefs(source: ArtifactManifest, opts: {
    sourceRunId: RunId;
}): ArtifactManifest;
