Builds a stable, documented audit / provenance record describing what happened to the edges and weights as [pagerank()] turned a raw edge list into the transition graph it scored. It is the backbone of reproducibility and of downstream diagnostics: it carries the row/edge counts, behavioral-weight coverage, normalization totals, the data that was dropped along the way (rows lost to NA / deduplication / self-loop removal, and authority-prior URLs that never folded onto a vertex), and the relevant [pagerank()] configuration. It also records the duplicate-edge policy used to build transitions, so callers can distinguish the default destination-level surfer from opt-in aggregate / link-slot models.
Details
## Structure and contract
The object is an S3 list with class `"transition_audit"` (a list was chosen over a bare list so that it prints a human-readable summary while remaining a plain, inspectable `list` for programmatic access — `audit$counts$n_edges` works as expected, mirroring the existing [audit_redirects()] / [audit_canonicals()] objects in this package). The documented top-level fields are **stable**; callers may rely on them being present.
- counts
A list of integer counts: `n_input_rows` (rows in the raw `edge_list_df`), `n_edges` (directed edges remaining after URL folding, deduplication and self-loop handling — i.e. the edges actually scored), and `n_vertices` (vertices in the returned result).
- coverage
A list describing behavioral-weight coverage: `weighted` (logical, whether a `weight_col` was in effect), `weight_col` (its name or `NULL`), `n_edges_weighted` (edges carrying a finite, positive weight), and `coverage` (the fraction `n_edges_weighted / n_edges`, or `NA_real_` when there are no edges / no weighting).
- normalization
A list of normalization totals: `pagerank_total` (sum of the returned PageRank scores; `< 1` when mass evaporated via nofollow, vanished robots-blocked pages, etc.).
- dropped
A list accounting for data removed during construction: `n_rows_na` (input rows dropped because `from`/`to` was `NA`), `n_rows_duplicate` (rows collapsed by edge deduplication), `n_self_loops` (self-loop edges dropped when `self_loops = "drop"`), `n_rows_collapsed` (total input rows that did not survive as distinct scored edges = `n_input_rows - n_edges`), `n_prior_unmatched` (authority prior URLs that did not fold onto any vertex; `NA_integer_` when no `prior_df` was supplied), and `n_robots_blocked` (URLs treated as robots.txt-blocked).
- duplicates
A list describing duplicate-edge handling: `policy` (the `duplicate_edge_policy` passed to [pagerank()]), `n_duplicate_rows` (post-fold duplicate input rows), `instance_count_col` (the internal audit column used by `"count_instances"`, or `NULL`), and `n_duplicate_instances` (the number of duplicate link instances folded into transition weights), and `duplicate_edges` (a compact data frame of counted edges with more than one link instance, or `NULL`).
- config
A list of the [pagerank()] arguments that materially shape the transition graph: `self_loops`, `drop_isolates_flag`, `reverse`, `weight_col`, `nofollow_col`, `nofollow_action`, `robots_blocked_action`, `prior_alpha`, `prior_transform`, `prior_inject_unmatched`, and the logical flags `has_redirects` / `has_canonicals` (whether that signal *materially* folded an edge — an effective no-op such as a self-canonical reads `FALSE`), `has_indexability`, and `has_prior`.
- mass
A list decomposing the internal stationary vector (which always sums to 1) into its accounted-for components: `reported` (the mass on returned, visible pages — equals the summed result scores), `sink` (the **evaporated mass**: authority sent to the synthetic nofollow-evaporation sink under `nofollow_action = "evaporate"`), `leaked` (the **leaked mass**: authority sent to the synthetic leak sink under `out_of_scope_fold = "leak"`, i.e. equity that flowed into out-of-scope-folded sources and left the measured graph — `0` when no leak occurred), `hidden` (the **hidden mass**: authority trapped on hidden / robots-blocked nodes removed under `robots_blocked_action = "vanish"`), and `total` (their sum, which reconciles to 1 by construction). These are the precise components of the deficit between the reported scores and 1 — it is evaporated, leaked and hidden mass, not undifferentiated "leakage". Each is `NULL` when the stationary vector is undefined (e.g. an empty graph).
- fold
A list recording how **out-of-scope folds** were handled — a composed fold-map entry whose *target* (the representative a crawled source folds onto) is not itself a crawled node, which silently invents a phantom vertex. `policy` (the `out_of_scope_fold` argument, `"relabel"`, `"keep"` or `"leak"`), `n_out_of_scope` (count of such entries), `applied` (logical: `TRUE` when they were acted upon — relabeled / folded through under `"relabel"`, or routed to the leak sink under `"leak"` — and `FALSE` when skipped / kept as crawled under `"keep"`; combine with `policy` to distinguish relabel from leak), and `out_of_scope` (a data frame of the offending `source` / `target` / `signal` rows, or `NULL` when there were none), and `collisions` (a data frame of **fold-target collisions** — uncrawled URLs that a fold relabeled a crawled source onto while they were ALSO independently linked, so the two silently merge into one vertex and the crawled page absorbs the inbound link equity of that uncrawled URL; columns `target`, `n_independent_refs` and the folded `source`(s) — or `NULL` when none). A collision triggers a `warning()` naming the merged URL(s). This diagnostic requires crawl-URL knowledge to distinguish an uncrawled fold target from a genuinely crawled leaf page, so it is only computed when an `indexability_df` is supplied to [pagerank()]; without it, `collisions` is `NULL`. Recorded regardless of `out_of_scope_fold` policy.
The constructor [new_transition_audit()] is internal plumbing for [pagerank()]; the object is normally obtained via `attr(result, "transition_audit")` (see [pagerank()]).