From 250107df4f79f358827e98c516e84e4bb8036b39 Mon Sep 17 00:00:00 2001
From: Ken <ken@kenotron.com>
Date: Wed, 27 May 2026 06:49:20 +0000
Subject: [PATCH] docs: add rage author motivation + cloudpack synthetic
 benchmarking approach
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rage: The real story is combining lage's dev ergonomics with BuildXL's
correctness at scale. Ken has wanted this synthesis for years since
co-creating lage. Frame the series around ergonomics vs correctness.

Cloudpack benchmarking: synthetic codebases generated from observed
attributes of real shipping code. Pipeline: observe real repo → produce
BenchProfile JSON → corpus_gen creates deterministic synthetic codebase
(same seed = byte-identical) → corpus_verify confirms conformance →
benchmark at various scales (100 to 50k modules).

Three TypeScript module variants (barrel, intermediate, leaf) with
realistic import structures, side effects, and ambient refs. JSON
configs, markdown docs fill out the shape. Tolerances: 2% file count,
5% byte/line count.

This solves 'we can't share the real codebase' for public benchmarks.
Worth a blog post on its own.

🤖 Generated with Amplifier

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .amplifier/AGENTS.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

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.