ken/crashtestdev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
1 changed files with 24 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.amplifier/AGENTS.md
+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
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 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.
@@ -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
**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 |
|---|-------|-------|----------------|
| 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. |
| 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. |
| 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. |
| 5 | node_modules in a Content-Addressed Store | The unsexy problem that kills CI. | 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. |
| 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 | 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 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 | 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 | 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
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
The core idea: the bundle is not a file, it's a query against a continuously-maintained
module graph. The architecture maps native linker innovations (ThinLTO, mold, BOLT/Propeller)
to JavaScript bundling at Microsoft Teams scale (50k+ modules).
**The outcome:** 604ms warm rebuilds at 50k modules. 50% less CDN bandwidth per
deploy. Dead code that actually stays dead. The mechanism: treat the bundle as a
query against a continuously-maintained module graph, not a file you rebuild from
scratch.
| # | 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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 | 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 | 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 | 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 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 | 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:
- 10k modules warm rebuild: 604ms analysis-only