PGO, Sample Profiles, And Thin Summary Optimization

This page documents the bounded release evidence for profile-guided

optimization, hosted sample-profile intake, and ThinLTO-style summary

optimization. The default developer path does not require profile collection or

profile application.

Run:

make pgo-thin-summary-check
make native-post-link-check

make native-post-link-check depends on make pgo-thin-summary-check, so

post-link layout evidence can only pass after profile artifacts, summary rows,

optimization decisions, and profile diagnostics are validated.

Evidence Files

• pgo-thin/profile-format.tsv defines profile fields for function counts,

edge counts, branch probabilities, indirect-call targets, hot/cold blocks,

startup windows, temporal order, hashes, and freshness.

• pgo-thin/profile-pipeline.tsv records instrumentation generation,

deterministic merge, hosted sample intake, validation, and opt-in profile

application.

• pgo-thin/thin-summary.tsv records call graph hashes, cross-module imports,

inline candidates, devirtualization candidates, code-size budgets, and

bounded parallel work.

• pgo-thin/optimization-decisions.tsv records profile-aware inlining,

hot/cold splitting, indirect-call promotion, branch layout, and hot/cold

placement.

• release/pgo-thin-profile-artifacts.tsv records current PGO and sample

profile artifacts.

• release/pgo-thin-merge-report.tsv records deterministic merge behavior.
• release/pgo-thin-summary-report.tsv records Thin summary output.
• release/pgo-thin-optimization-report.tsv records correctness, wall-clock,

RSS, binary-size, and reproducibility evidence for profile-guided decisions.

• release/pgo-thin-diagnostics-report.tsv records stable negative

diagnostics.

• perf/pgo-thin-performance-evidence.tsv records performance evidence.
• compat/pgo-thin-summary-contract.tsv records release ownership and gate

wiring.

• tools/pgo-thin-summary-check.py validates the evidence and fixtures.

Profile Artifacts

Profile artifacts must bind to the workload, source hash, binary hash, profile

hash, profile kind, and freshness budget. Instrumentation PGO and hosted sample

profiles share the same validation path after intake. Profile use is optional:

release builds may consume stable profile artifacts, but a build without a

profile must remain reproducible.

Profile artifacts include:

• function counts;
• edge counts;
• branch probabilities;
• indirect-call targets;
• hot and cold block classes;
• startup windows;
• temporal function order.

Thin Summary Optimization

Thin summaries are compact module records. They do not move target-specific

behavior into the frontend. A summary records the call graph hash, imported

symbols, inline candidates, devirtualization candidates, code-size budget, and

parallel job budget.

Profile-guided decisions may apply only when:

• the profile source hash and binary hash match the compilation input;
• the profile is not stale;
• merge output is deterministic and conflict-free;
• correctness evidence exists;
• wall-clock, RSS, and binary-size budgets pass;
• the reproducibility hash is stable.

Diagnostics

The gate rejects profile and summary problems with stable diagnostics:

PGO_PROFILE_STALE
PGO_PROFILE_HASH_MISMATCH
PGO_INCOMPATIBLE_BINARY
PGO_MISSING_SOURCE
PGO_MERGE_CONFLICT
PGO_SIZE_REGRESSION

These diagnostics fail closed. A stale or incompatible profile is ignored only

when the command explicitly chooses an unprofiled reproducible build mode.

Documentation Impact

Compiler, optimizer, native toolchain, or release changes that alter profile

format, merge behavior, sample intake, Thin summary contents, or profile-guided

optimization decisions must update this page, the PGO/thin evidence rows,

release notes, and the public reference index in the same change.