docs: reframe both series to lead with outcomes, not internals

Key principle added to standing rules: 'Lead with outcomes, not internals.
Nobody cares about a fingerprinting algorithm. They care that their builds
stop lying.'

Rage series retitled:
- 'Two-Phase Fingerprinting: BuildXL's Deep Magic' → 'How We Made the Cache Stop Lying'
- 'Hooking Syscalls Without a Kernel Driver' → 'Zero-Config File Watching Across Three Operating Systems'
- 'TypeScript 7 Makes the Build Harness More Important' → 'TypeScript 7 Is 10x Faster. Your Builds Aren't.'
- 'node_modules in a Content-Addressed Store' → '90 Seconds to 300 Milliseconds: Fixing CI Install Times'
- 'What I Learned Maintaining Lage and Why I Rewrote It' → 'The Architecture Mistake I Made in Lage'

Cloudpack series retitled:
- 'The Bundle Is Not a File' → '604ms Rebuilds at 50,000 Modules'
- 'The 2KB Module Summary' → '50KB Down to 2KB: Why We Stopped Parsing Source Files'
- 'Dead Code That Actually Stays Dead' → 'We Shipped 40% Less JavaScript and Nobody Noticed'
- 'The Service Worker as ld.so' → '50% Less Bandwidth Per Deploy'
- 'Signing Manifests, Not Code' → 'A Compromised Server Can\'t Inject Code'

🤖 Generated with Amplifier

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
This commit is contained in:
Ken
2026-05-27 06:42:25 +00:00
parent 6241656f55
commit a7f2e71a4a
+24 -14
View File
@@ -185,6 +185,11 @@ Not decoration, but content: architecture diagrams, flow charts, before/after
comparisons, concept illustrations. If 500+ words pass without a visual, ask comparisons, concept illustrations. If 500+ words pass without a visual, ask
what would replace them. what would replace them.
**Lead with outcomes, not internals.** Nobody cares about a fingerprinting
algorithm. They care that their builds stop lying. Nobody cares about ld.so
analogies. They care about 50% less CDN bandwidth. The mechanism is the proof,
not the headline. Name the result in the title. Explain the how in the body.
**No blog chrome.** No comments, no share buttons, no "related posts" sidebar, **No blog chrome.** No comments, no share buttons, no "related posts" sidebar,
no newsletter popups, no social proof widgets. The content quality is the no newsletter popups, no social proof widgets. The content quality is the
credibility signal. If it needs a "clap" button, the writing isn't good enough. credibility signal. If it needs a "clap" button, the writing isn't good enough.
@@ -193,14 +198,18 @@ credibility signal. If it needs a "clap" button, the writing isn't good enough.
Source: kenotron-ms/rage repo + ~/workspace/family/Work/Reference/BuildXL spec Source: kenotron-ms/rage repo + ~/workspace/family/Work/Reference/BuildXL spec
**Lead with outcomes, explain internals as the "how."** Nobody cares about a
fingerprinting algorithm. They care that their builds stop lying. The mechanism
is the proof, not the headline.
| # | Title | Angle | Visuals Needed | | # | Title | Angle | Visuals Needed |
|---|-------|-------|----------------| |---|-------|-------|----------------|
| 1 | Your Build Cache Is Lying to You | The silent stale cache problem. Make it concrete. | Flow: declared vs observed inputs. Before/after diagram of cache miss. | | 1 | Your Build Cache Is Lying to You | The silent stale cache problem. Make it concrete. | Flow: declared vs observed inputs. Before/after diagram of cache miss. |
| 2 | Two-Phase Fingerprinting: BuildXL's Deep Magic | WF→pathset→SF algorithm deep-dive. | Architecture: the two-phase lookup flow. Code walkthrough diagrams. | | 2 | How We Made the Cache Stop Lying | The fix: observed inputs replace declared ones. Two-phase fingerprinting is the mechanism. | Architecture: the two-phase lookup flow. Code walkthrough diagrams. |
| 3 | Hooking Syscalls Without a Kernel Driver | Three OS, three mechanisms. Most technically dense. | Side-by-side: macOS interpose / Linux eBPF / Windows Detours. Animated (Remotion): syscall interception flow. | | 3 | Zero-Config File Watching Across Three Operating Systems | You don't configure what files to watch. The sandbox just watches. How: three OS-specific hooks. | Side-by-side: macOS interpose / Linux eBPF / Windows Detours. Animated (Remotion): syscall interception flow. |
| 4 | TypeScript 7 Makes the Build Harness More Important | Counter-intuitive thesis. Widest reach. | Comparison: single-machine vs distributed. The parallelism table as a visual. | | 4 | TypeScript 7 Is 10x Faster. Your Builds Aren't. | tsgo is 10x faster on one machine. Builds don't run on one machine. The bottleneck moved. | Comparison: single-machine vs distributed. The parallelism table as a visual. |
| 5 | node_modules in a Content-Addressed Store | The unsexy problem that kills CI. | Flow: lockfile → CAS → hardlink restore. Before/after CI times. | | 5 | 90 Seconds to 300 Milliseconds: Fixing CI Install Times | Per-package content-addressed storage. 1 miss + 1,499 hardlinks instead of re-downloading everything. | Flow: lockfile → CAS → hardlink restore. Before/after CI times. |
| 6 | What I Learned Maintaining Lage and Why I Rewrote It | Personal narrative, meta post. | Timeline: lage → BuildXL integration hack → rage. | | 6 | The Architecture Mistake I Made in Lage | File access was an afterthought, not a primitive. What that cost, and what starting over taught me. | Timeline: lage → ceiling → rage. Before/after architecture diagram. |
Each post stands alone but gains context from the series. The series landing page Each post stands alone but gains context from the series. The series landing page
shows progress (like makingsoftware.com's progress bar) and creates anticipation shows progress (like makingsoftware.com's progress bar) and creates anticipation
@@ -210,18 +219,19 @@ for upcoming posts.
Source: ~/workspace/wundler/ (kenotron-ms/cloudpack on GitHub) + architect brief + exec summary Source: ~/workspace/wundler/ (kenotron-ms/cloudpack on GitHub) + architect brief + exec summary
The core idea: the bundle is not a file, it's a query against a continuously-maintained **The outcome:** 604ms warm rebuilds at 50k modules. 50% less CDN bandwidth per
module graph. The architecture maps native linker innovations (ThinLTO, mold, BOLT/Propeller) deploy. Dead code that actually stays dead. The mechanism: treat the bundle as a
to JavaScript bundling at Microsoft Teams scale (50k+ modules). query against a continuously-maintained module graph, not a file you rebuild from
scratch.
| # | Title | Angle | Visuals Needed | | # | Title | Angle | Visuals Needed |
|---|-------|-------|----------------| |---|-------|-------|----------------|
| 1 | The Bundle Is Not a File | Linker-world analogy. ThinLTO/mold/BOLT mapped to JS bundling. "Database, not compiler." | Architecture: the 3-phase pipeline. Side-by-side: linker innovation bundler equivalent. | | 1 | 604ms Rebuilds at 50,000 Modules | The outcome first. Then how: the bundle is a query, not a file. Linker innovations (ThinLTO, mold, BOLT) mapped to JS. | Architecture: the 3-phase pipeline. Before/after: traditional bundler vs cloudpack. |
| 2 | The 2KB Module Summary That Replaced a Full Parse | ModuleSummary as the core data structure. 25x compression. Content-addressed cache. | Diagram: source file (50KB) → ModuleSummary (2KB). The rayon parallel loop. | | 2 | 50KB Down to 2KB: Why We Stopped Parsing Source Files | 25x compression. The module summary replaces full parsing. Content-addressed cache means unchanged files cost zero. | Diagram: source (50KB) → summary (2KB). The parallel loop. Memory budget at 50k modules. |
| 3 | Dead Code That Actually Stays Dead | Two-layer tree-shaking: module-level (conservative) + function-level (aggressive via call-edge graph). SideEffectMarker AST analysis. | Flow: BFS reachability + Tarjan SCC + call-edge DCE walk. Before/after module counts. | | 3 | We Shipped 40% Less JavaScript and Nobody Noticed | Two-layer tree-shaking that actually works. Module-level conservative + function-level aggressive via call-edge graph. | Flow: reachability → SCC → DCE walk. Before/after bundle sizes. |
| 4 | The Service Worker as ld.so | Adaptive Bundle Service. Delta manifests. Browser tells server what it has, server returns only what's missing. | Architecture: CDN chunks as shared libraries, SW as dynamic linker. Delta computation flow. | | 4 | 50% Less Bandwidth Per Deploy | Users re-download the whole bundle when 1% changed. Delta manifests fix this. Browser says what it has, server returns what's missing. | Architecture: delta computation flow. Before/after CDN bandwidth. |
| 5 | Your Users Are Teaching the Bundler | Profile-Guided Optimization from real browser sessions. C³ co-request clustering. SQLite co-request matrix. Prefetch without rebuild. | The feedback loop: browser sessions → JSONL → SQLite → C³ clustering → manifest hints. | | 5 | Your Users Are Already Telling You How to Bundle | Real browser sessions drive chunk grouping. No rebuild required. The optimization loop runs on live traffic. | The feedback loop: sessions → co-request matrix → clustering → manifest hints. |
| 6 | Signing Manifests, Not Code | Ed25519 signing of chunk hashes. Threat model: ABS compromise ≠ code injection. PGO fields excluded from signature. | Security model diagram: what's signed, what's not, what an attacker can/can't do. | | 6 | A Compromised Server Can't Inject Code | Ed25519 signing of chunk hashes. The threat model: what an attacker can and can't do if they own the manifest server. | Security model diagram: what's signed vs what's advisory. Attack surface comparison. |
Key numbers for receipts: Key numbers for receipts:
- 10k modules warm rebuild: 604ms analysis-only - 10k modules warm rebuild: 604ms analysis-only