Infrastructure: Enforce package-cost budgets and production dependency boundaries #4341

Goal

Promote the package-cost foundation delivered by #4253 into reviewed, required regression gates. Parent: #4275.

Status - 2026-10-01

Open; measurement and advisory reporting already exist. This follow-up preserves the unfinished gate, dependency, and measurement-completeness criteria from #4253. It does not require rebuilding the measurement harness.

PRs #4284, #4289, #4295, #4297, and #4335 delivered seven supported-public-import scenarios on macOS and Windows, checked-in baselines, optional-module presence/absence rules, esbuild attribution, and persistent advisory PR reports. Two measurements at merged-main commit c3a89b0b7 produced identical inputs for all 14 platform/scenario combinations.

The current measurement externalizes React/React Native and measures tree-shaken package JavaScript, not total application or native binary size. PR #4335 intentionally replaced Metro shell-relative measurements with this metric.

Remaining scope

• Establish normal variance for the current esbuild metric, then approve per-scenario absolute and percentage growth budgets. Retain raw bytes as the primary metric; gzip and module attribution are diagnostics.
• Enforce production manifest/source dependency allowlists, including unused declarations. packages/agentic/components/package.json still declares Callout and suppresses it through a Knip ignore; do not widen the approved source boundary merely to pass a check.
• Complete the original measurement coverage for public primitives and packed components/design archives. The current catalog scenario imports the package root, not the separate /primitives entry point; the measurement report does not include packed archive sizes.
• Record reproducible commit, bundler/configuration, dependency/toolchain, and platform identities. Ordinary measurement must not rewrite or accept a candidate baseline.
• Promote checks through the actual required-status path. Current main rules require only PR, and .github/workflows/pr.yml does not include bundle-size in that aggregate's dependencies.

Acceptance criteria

• One documented root command produces complete consumer, public-primitive, reachability, dependency, and packed-archive measurements.
• Repeated runs in the declared environment have identical budget inputs; diagnostic/nondeterministic metadata is excluded from comparisons.
• macOS and Windows baselines cover every required scenario and list contributing workspace packages. Other platform coverage is explicit, not implied.
• The approved production dependency boundary is enforced against manifests and production source; unused Callout declarations/ignores are removed unless a reviewed production use justifies them.
• Flex-only paths exclude reverse legacy construction and runtime color derivation; explicit opt-ins positively prove their intended implementation remains present.
• Checked-in absolute and percentage budgets fail a required check when either limit is exceeded. Dependency/reachability violations also fail.
• Missing scenarios, incompatible baselines, or analysis failures cannot be accepted as improvements or silently skipped.
• yarn bundle-size:update remains explicit, and baseline/budget increases require reviewed rationale tied to the implementation.
• PR summaries/comments and diagnostic artifacts remain available on failures; the intended gate is demonstrably required by repository policy.
• Documentation, relevant tests, build/lint/format/publishing/lockfile checks, and changesets for public package changes are complete.

Evidence

• Current fixture and reproduction commands
• Scenarios
• Advisory comparison implementation
• Current component manifest
• Actual advisory PR report
• Delivered milestone: Infrastructure: Add bundle-size measurement and advisory PR reporting #4253. Product/source-boundary ownership remains with Components workstream #4274; this is shared Components/Theming infrastructure.
• Related required-native operating policy: Infrastructure: Qualify and require native Storybook CI coverage #4349. This issue independently owns the required package-cost status and budgets.