Typed-feedback profile replay with freshness validation and guarded specialization

[proggeramlug]

Context

Follow-up to #1849.

Perry can emit typed-feedback-trace.json, and its typed native fast paths already retain runtime guards, explicit fallback edges, native-region artifacts, and verifier checks. The compiler does not currently consume a prior trace, so #1849's optional profile-replay item was intentionally split out when closing that umbrella issue.

Goal

Add opt-in typed-feedback profile replay as advisory compiler input. A valid profile may help select or prioritize an existing guarded specialization, but it must never become runtime truth: every selected path must retain the appropriate runtime guard and semantics-preserving fallback.

Requirements

• Define a versioned replay schema with enough identity data to detect stale input, including source/module identity, site identity, schema/compiler compatibility, and target-relevant metadata.
• Add an explicit compiler input, preferably --typed-feedback-profile <path>, without changing default builds.
• Match observations to stable specialization sites and consume only supported observation kinds.
• Ignore stale, mismatched, unknown, or incompatible entries for specialization. Report why each entry/profile was rejected.
• Treat profile facts as hints only. TypeScript annotations and profile observations must not bypass runtime shape, representation, bounds, ownership, alias, lifetime, or method-identity guards.
• Preserve the generic fallback or side exit for every replay-selected fast path.
• Record accepted and rejected replay facts in native-representation artifacts and --explain-lowering, including freshness and selection reasons.
• Keep replay deterministic for the same source, profile, target, and compiler inputs.

Acceptance criteria

• A valid profile fixture selects at least one supported guarded fast path, and the emitted IR/artifact proves both the guard and fallback remain present.
• Runtime values that disagree with the replayed observation take the fallback and remain JavaScript-equivalent to an unprofiled build.
• Profiles with a source/module hash mismatch, schema mismatch, incompatible target metadata, unknown site, or unsupported observation kind do not affect lowering.
• Malformed explicit profile input produces an actionable diagnostic; stale or incompatible well-formed input is safely ignored and explained.
• The native-region verifier rejects any record that claims profile-directed specialization without a consumed replay fact, matching runtime guard, and explicit fallback/materialization record.
• Tests cover valid replay, each freshness/mismatch rejection, guard failure, semantic parity, deterministic output, and --explain-lowering reporting.
• User-facing documentation describes capture, replay, freshness behavior, and the fact that profiles are advisory.

Out of scope

• Removing runtime guards based on profile observations.
• Treating TypeScript annotations or a profile as authoritative runtime types.
• Cross-version best-effort replay when the schema/compiler compatibility check fails.
• A general-purpose PGO or inlining framework beyond typed-native specialization-site selection.