diff --git a/.amplifier/AGENTS.md b/.amplifier/AGENTS.md index 2e58766..ed180cc 100644 --- a/.amplifier/AGENTS.md +++ b/.amplifier/AGENTS.md @@ -244,3 +244,43 @@ Key numbers for receipts: - 50k modules in memory as summaries: ~100MB (fits L3 cache) - ABS delivery: ~50% CDN bandwidth saved per deploy - 50k modules, 10k DAU, 1% weekly churn: saves ~47 GB/week + +## Rage Series: Author's Motivation + +The real story behind rage is not "I rewrote lage in Rust." It's: "I've wanted +to combine lage's developer ergonomics with BuildXL's correctness at scale for +years, and I finally got to do it." Lage gives you the dev experience. BuildXL +gives you the guarantees. They've never existed in the same tool. Rage is the +synthesis Ken has been thinking about since he co-created lage. Frame the series +around that tension: ergonomics vs. correctness, and how you get both. + +## Cloudpack: Benchmarking With Synthetic Data + +Cloudpack benchmarks against synthetic codebases generated from observed +attributes of real shipping code. The pipeline: + +1. **Observe**: `wundler-bench` scans a real repo and produces a `BenchProfile` + JSON capturing its statistical fingerprint: file counts by extension, + average file sizes, directory distribution, package structure. + +2. **Generate**: `corpus_gen` creates a deterministic synthetic codebase matching + the profile. Same seed = byte-identical output. TypeScript modules are + generated in three variants (barrel, intermediate, leaf) with realistic + import structures, side effects, and ambient refs. JSON configs, markdown + docs, and fallback files fill out the shape. + +3. **Verify**: `corpus_verify` confirms the generated corpus matches the profile + within tolerances (default: 2% file count, 5% byte/line count). + +4. **Benchmark**: Run the pipeline against the synthetic corpus at various + scales (100, 1k, 5k, 10k, 50k modules) and measure. + +This approach solves the "we can't share the real codebase" problem. The +synthetic corpus has the same statistical properties (file sizes, dependency +fan-out, side-effect density) as the real Teams codebase without containing +any proprietary code. The benchmarks are reproducible, scalable, and public. + +This is worth a blog post on its own: "How We Benchmark a Bundler Without +Sharing the Codebase." The profile schema, the archetype generators (barrel +vs intermediate vs leaf modules), the determinism guarantees (same seed = +identical bytes), and the conformance checks are all interesting.