Close dogfood + postmortem post: portability boundary located at 21m 23s
Three things in one commit: 1. Dogfood close: goals/blog-date-prefix.md flips pending → shipped, merge_sha 72919e8, pr_number 55. ALL_GOALS entry added. 2. Postmortem post: 21m 23s data-driven measured against the ≤30min prediction from PR #53 postmortem. Within band. Three datapoints on the cost-flattening chain (PR #42 evening, PR #53 8m8s fixed- enum, PR #55 21m23s data-driven) align with mechanical model: helper stays mechanical, migration tooling grows with surface, Layer-3 wrapper byte-identical across all three. 3. Scorecard image with three-column comparison + boundary callout. Co-Authored-By: Claude Opus 4.7 <[email protected]>
6 files changed · +188 −3
content/blog/sama-v2-portability-boundary-found.md
+79
−0
| @@ -0,0 +1,79 @@ | ||
| 1 | +# 21 minutes 23 seconds — the portability boundary is empirically located | |
| 2 | + | |
| 3 | +The [second-URL-refactor postmortem](/blog/2026-05/sama-v2-second-url-refactor-postmortem) closed with two falsifiable subclaims. The third URL refactor on this site happened today and measured the second one: | |
| 4 | + | |
| 5 | +> *"A data-shaped refactor stays under 30 minutes. Pick /blog/<slug> → /blog/<yyyy-mm>/<slug>. Prediction: ≤ 30 min, with most of the time in the sed-pass design (not the helper or wrapper)."* | |
| 6 | + | |
| 7 | +Wall-clock from `git checkout -b blog-date-prefix` to deploy success: **21 minutes 23 seconds**. Within the predicted band, on the faster side. | |
| 8 | + | |
| 9 | +Three datapoints now. The pattern stays portable; the cost stays bounded; the floor differs by kind: | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | +## The three datapoints | |
| 14 | + | |
| 15 | +| | PR #42 (first) | PR #53 (fixed-enum) | PR #55 (data-driven) | | |
| 16 | +|---|---|---|---| | |
| 17 | +| Wall-clock | an evening (~3h) | **8m 8s** | **21m 23s** | | |
| 18 | +| Helper imports data | none | none | `ALL_POSTS` | | |
| 19 | +| Helper LOC | 13 | 13 | 24 | | |
| 20 | +| Migration mechanism | sed (one-liner) | sed (one-liner) | Bun script (~50 LOC) | | |
| 21 | +| References rewritten | 49 | ~22 | 173 | | |
| 22 | +| Files touched | 19 | 17 | 46 | | |
| 23 | +| Over-rewrites | 0 | 1 (caught + reverted) | 1 wider (5+ files) | | |
| 24 | +| Verifier verdict | 7/7 ✓ | 7/7 ✓ | 7/7 ✓ | | |
| 25 | + | |
| 26 | +Three observations. | |
| 27 | + | |
| 28 | +## What the prediction got right | |
| 29 | + | |
| 30 | +**The helper itself stayed mechanical.** PR #53's 13-line `rewriteOldSamaDisciplineUrl` was a near-byte-for-byte copy of PR #42's `rewriteOldGitUrl`. PR #55's `rewriteOldBlogUrl` is 24 lines — 13 of original shape (regex match, null return on miss) plus 11 lines of `ALL_POSTS.find` + `date.slice(0, 7)` + new-URL construction. The added 11 lines are *all* the data-driven part. The pattern itself didn't grow; just the lookup pipe at the front of it. | |
| 31 | + | |
| 32 | +**The Layer-3 wrapper stayed identical across all three.** The same 11-line block — `if (newPath !== null) return new Response(null, { status: 301, headers: { Location: newPath, ... } })` — appears three times in `d21_handlers_fallback.ts` now, adjacent to each other. Pure copy-paste with one identifier change. Code review would catch any drift between them mechanically. | |
| 33 | + | |
| 34 | +**The verifier stayed 7/7 ✓ across all three merges.** Anti-fudge gate held. None of the three refactors required §4 verifier changes. | |
| 35 | + | |
| 36 | +## What surprised — the migration cost grew | |
| 37 | + | |
| 38 | +The data-driven refactor isn't just *the helper has a lookup*. The migration tooling had to grow too: | |
| 39 | + | |
| 40 | +- **One sed line → 50-line Bun script.** The git-url and sama-discipline migrations were `sed -i -E 's|/old/.*|/new/...|g'` — one shell line. The blog migration needed per-slug substitution because each new URL depends on the post's date. That meant: iterate ALL_POSTS, build a `[old, new]` table, sort by slug length DESC to avoid prefix collisions, iterate every file, do N replaceAll passes per file. Still mechanical, but the tooling is now ~50 LOC instead of 1. | |
| 41 | +- **One over-rewrite → wider over-rewrite.** Same pattern-risk as PR #53 (sed matching inside filesystem paths), but here the script touched `content/blog/<slug>.md` strings — 5+ files affected instead of 1. Reverted with a counter-sed that restored `content/blog/YYYY-MM/<slug>.md` to `content/blog/<slug>.md`. Total recovery: ~2 minutes, but it's a real pattern-risk that gets bigger as the refactor surface grows. | |
| 42 | +- **Spoof guard.** The fixed-enum refactors didn't need one: the regex enumerated exactly the valid slugs, so URL forgery was impossible by construction. The data-driven handler reads `:yyyymm` from the URL — a forged `/blog/9999-99/<valid-slug>` would render the post if the handler didn't validate. Added a one-line `entry.date.slice(0, 7) !== yyyymm → 404` guard. Trivial, but a new class of concern. | |
| 43 | +- **Three test failures after migration.** The migration substituted URL strings inside test assertions AND inside filesystem-path strings (the same sed-bug, wider). Three tests broke; all three were mechanical to fix (revert the over-rewrites, then update remaining stale URLs in CONTRIBUTING.md which the script missed because it's at root, not under `content/`). | |
| 44 | + | |
| 45 | +The 21 minutes split roughly: **~10 min on the new code** (helper, sibling test, handler with spoof guard, Bun route, sitemap, blog index, edit-resolve update) + **~6 min on the migration script + run** + **~3 min recovering from over-rewrites + missed-file** + **~2 min on PR + deploy**. The new-code time was actually the same as PR #53; the difference is *everything around it*. | |
| 46 | + | |
| 47 | +## Where the boundary sits | |
| 48 | + | |
| 49 | +Pre-PR #53, the open question was: *does the b32_<old>_url_redirect pattern only work for fixed-enum refactors?* | |
| 50 | + | |
| 51 | +Answer after PR #55: **no, the pattern works for data-driven too — the helper just imports the registry that owns the new URL's variable component.** Layer-1 importing Layer-0 is fine; SAMA explicitly allows it. The helper stays pure, the Response wrapper stays identical, the structural shape is preserved. | |
| 52 | + | |
| 53 | +What grows with data-driven is *the migration*, not *the design*. And the migration is one-shot tooling that doesn't ship with the runtime — `scripts/migrate-blog-urls.ts` is in the repo but never imported by the application. The runtime cost is identical; only the development-time cost of *one* migration changed. | |
| 54 | + | |
| 55 | +So the empirical boundary is: | |
| 56 | +- **Fixed-enum URL refactors: ~8 min wall-clock**, dominated by deploy time. | |
| 57 | +- **Data-driven URL refactors: ~21 min wall-clock**, with the extra time going entirely to (a) writing the migration script, (b) recovering from sed-pattern collisions when the rewrite surface is larger, (c) adding the spoof guard. | |
| 58 | + | |
| 59 | +Three datapoints isn't a law of nature. But the *shape* of the cost difference is mechanical: more files to migrate = more risk of over-rewrite collisions = more recovery time. Future data-driven refactors should land in the same band as long as the migration scope stays under ~200 references. | |
| 60 | + | |
| 61 | +## What the empirical chain has now | |
| 62 | + | |
| 63 | +After the [first postmortem](/blog/2026-05/sama-v2-git-url-refactor-postmortem) (PR #42), the claim was *"this pattern is reusable in principle"*. | |
| 64 | + | |
| 65 | +After the [second postmortem](/blog/2026-05/sama-v2-second-url-refactor-postmortem) (PR #53), the claim was *"this pattern is reusable in practice for fixed-enum URLs, measured 7.4× faster than the first instance"*. | |
| 66 | + | |
| 67 | +After this post (PR #55), the claim is *"this pattern is reusable for data-driven URLs too; the cost grows with migration surface but stays bounded; three datapoints align with the predictive model from the second postmortem"*. | |
| 68 | + | |
| 69 | +Every claim above is on git: helper code, sibling tests, /goal contracts, plan-vs-actual postmortems, wall-clock measurements. *Compliance proves the rules were followed; delta proves they were worth following* — and now, three deltas confirm the rule about *URL refactor cost* is itself stable across pattern variants. | |
| 70 | + | |
| 71 | +## What's next on this chain | |
| 72 | + | |
| 73 | +Two falsifiable subclaims that the next iteration could test: | |
| 74 | + | |
| 75 | +1. **A fourth refactor of the same shape lands in the same band.** Pick another fixed-enum (e.g. `/guides/<slug>` → `/guides/agent/<slug>` if guides ever subdivide). Prediction: ≤ 10 min, since the pattern is now mature and the deploy-time floor dominates. | |
| 76 | + | |
| 77 | +2. **A data-driven refactor with a much larger surface still stays bounded.** Construct a scenario with ~500 references (e.g. if the blog grows to 100+ posts, doing another date-restructuring would trigger). Prediction: ≤ 45 min, because the marginal cost is in over-rewrite recovery, not in helper design. | |
| 78 | + | |
| 79 | +Either result informative. Until then: three URL refactors, three postmortems, three wall-clock measurements, one stable pattern. The chain ratchets again. | |
goals/blog-date-prefix.md
+3
−3
| @@ -3,9 +3,9 @@ slug: blog-date-prefix | ||
| 3 | 3 | title: Move /blog/<slug> → /blog/<yyyy-mm>/<slug> — data-driven refactor portability test |
| 4 | 4 | date: 2026-05-25 |
| 5 | 5 | branch: blog-date-prefix |
| 6 | -pr_number: null | |
| 7 | -merge_sha: null | |
| 8 | -status: pending | |
| 6 | +pr_number: 55 | |
| 7 | +merge_sha: 72919e8 | |
| 8 | +status: shipped | |
| 9 | 9 | related_posts: [sama-v2-second-url-refactor-postmortem] |
| 10 | 10 | --- |
| 11 | 11 | |
public/images/portability-boundary-found.png
+0
−0
public/images/portability-boundary-found.svg
+90
−0
| @@ -0,0 +1,90 @@ | ||
| 1 | +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 720" width="1200" height="720"> | |
| 2 | + <rect width="1200" height="720" fill="#0a0a0a"/> | |
| 3 | + | |
| 4 | + <!-- Header --> | |
| 5 | + <g font-family="ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Consolas, monospace"> | |
| 6 | + <text x="80" y="46" font-size="20" font-weight="600" fill="#909090">Portability-boundary test — data-driven URL refactor</text> | |
| 7 | + <text x="80" y="92" font-size="32" font-weight="700" fill="#e8e8e8">Predicted 20–30 min. Landed in 21m 23s.</text> | |
| 8 | + <text x="80" y="120" font-size="14" fill="#7a7a7a">Pattern portable across DATA-DRIVEN refactors. Cost-flattening holds, but the floor is higher than for fixed-enum.</text> | |
| 9 | + </g> | |
| 10 | + | |
| 11 | + <!-- Three-row comparison: PR #42 / PR #53 / PR #55 --> | |
| 12 | + <g font-family="ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Consolas, monospace" font-size="13" font-weight="600" letter-spacing="2"> | |
| 13 | + <text x="100" y="172" fill="#909090">DIMENSION</text> | |
| 14 | + <text x="420" y="172" fill="#909090">PR #42 (FIRST)</text> | |
| 15 | + <text x="650" y="172" fill="#909090">PR #53 (FIXED-ENUM)</text> | |
| 16 | + <text x="900" y="172" fill="#909090">PR #55 (DATA-DRIVEN)</text> | |
| 17 | + </g> | |
| 18 | + <line x1="80" y1="184" x2="1120" y2="184" stroke="#2a2a2a" stroke-width="1"/> | |
| 19 | + | |
| 20 | + <g font-family="ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Consolas, monospace" font-size="15"> | |
| 21 | + | |
| 22 | + <text x="100" y="216" fill="#c8c8c8">wall-clock</text> | |
| 23 | + <text x="420" y="216" fill="#8a8a8a">an evening</text> | |
| 24 | + <text x="650" y="216" fill="#7ec77e" font-weight="700">8m 8s</text> | |
| 25 | + <text x="900" y="216" fill="#c89a3a" font-weight="700">21m 23s</text> | |
| 26 | + | |
| 27 | + <text x="100" y="246" fill="#c8c8c8">helper imports data</text> | |
| 28 | + <text x="420" y="246" fill="#8a8a8a">none (fixed regex)</text> | |
| 29 | + <text x="650" y="246" fill="#8a8a8a">none (fixed regex)</text> | |
| 30 | + <text x="900" y="246" fill="#c89a3a">ALL_POSTS</text> | |
| 31 | + | |
| 32 | + <text x="100" y="276" fill="#c8c8c8">helper LOC</text> | |
| 33 | + <text x="420" y="276" fill="#8a8a8a">13</text> | |
| 34 | + <text x="650" y="276" fill="#8a8a8a">13</text> | |
| 35 | + <text x="900" y="276" fill="#c89a3a">24 (lookup + slice)</text> | |
| 36 | + | |
| 37 | + <text x="100" y="306" fill="#c8c8c8">sibling-test cases</text> | |
| 38 | + <text x="420" y="306" fill="#8a8a8a">9</text> | |
| 39 | + <text x="650" y="306" fill="#8a8a8a">12</text> | |
| 40 | + <text x="900" y="306" fill="#c8c8c8">7</text> | |
| 41 | + | |
| 42 | + <text x="100" y="336" fill="#c8c8c8">migration mechanism</text> | |
| 43 | + <text x="420" y="336" fill="#8a8a8a">sed (one-liner)</text> | |
| 44 | + <text x="650" y="336" fill="#8a8a8a">sed (one-liner)</text> | |
| 45 | + <text x="900" y="336" fill="#c89a3a">Bun script (~50 LOC)</text> | |
| 46 | + | |
| 47 | + <text x="100" y="366" fill="#c8c8c8">references rewritten</text> | |
| 48 | + <text x="420" y="366" fill="#8a8a8a">49</text> | |
| 49 | + <text x="650" y="366" fill="#8a8a8a">~22</text> | |
| 50 | + <text x="900" y="366" fill="#c8c8c8">173</text> | |
| 51 | + | |
| 52 | + <text x="100" y="396" fill="#c8c8c8">files touched (migration)</text> | |
| 53 | + <text x="420" y="396" fill="#8a8a8a">19</text> | |
| 54 | + <text x="650" y="396" fill="#8a8a8a">17</text> | |
| 55 | + <text x="900" y="396" fill="#c8c8c8">46</text> | |
| 56 | + | |
| 57 | + <text x="100" y="426" fill="#c8c8c8">handler complication</text> | |
| 58 | + <text x="420" y="426" fill="#8a8a8a">drop owner from sig</text> | |
| 59 | + <text x="650" y="426" fill="#8a8a8a">rename route segment</text> | |
| 60 | + <text x="900" y="426" fill="#c89a3a">yyyymm spoof-guard</text> | |
| 61 | + | |
| 62 | + <text x="100" y="456" fill="#c8c8c8">over-rewrite incidents</text> | |
| 63 | + <text x="420" y="456" fill="#8a8a8a">0</text> | |
| 64 | + <text x="650" y="456" fill="#8a8a8a">1 (caught + reverted)</text> | |
| 65 | + <text x="900" y="456" fill="#c89a3a">1 wider (5+ files)</text> | |
| 66 | + | |
| 67 | + <text x="100" y="486" fill="#c8c8c8">test count delta</text> | |
| 68 | + <text x="420" y="486" fill="#8a8a8a">+9 (379 → 388)</text> | |
| 69 | + <text x="650" y="486" fill="#8a8a8a">+12 (407 → 419)</text> | |
| 70 | + <text x="900" y="486" fill="#c8c8c8">+7 (419 → 426)</text> | |
| 71 | + | |
| 72 | + <text x="100" y="516" fill="#c8c8c8">verifier verdict</text> | |
| 73 | + <text x="420" y="516" fill="#7ec77e">7/7 ✓</text> | |
| 74 | + <text x="650" y="516" fill="#7ec77e">7/7 ✓</text> | |
| 75 | + <text x="900" y="516" fill="#7ec77e">7/7 ✓</text> | |
| 76 | + </g> | |
| 77 | + | |
| 78 | + <!-- Bottom callout --> | |
| 79 | + <rect x="80" y="552" width="1040" height="148" fill="#101a10" stroke="#1f3f1f" stroke-width="1" rx="6"/> | |
| 80 | + <g font-family="ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Consolas, monospace"> | |
| 81 | + <text x="100" y="584" font-size="16" font-weight="600" fill="#7ec77e">Boundary empirically located between PR #53 and PR #55.</text> | |
| 82 | + <text x="100" y="610" font-size="14" fill="#c8c8c8">FIXED-ENUM refactors land in ~8 min (template copy + slug rename + paste).</text> | |
| 83 | + <text x="100" y="630" font-size="14" fill="#c8c8c8">DATA-DRIVEN refactors land in ~21 min (template copy + add ALL_POSTS lookup + spoof guard + migration script + over-rewrite recovery).</text> | |
| 84 | + <text x="100" y="652" font-size="14" fill="#c8c8c8">Both within predicted bands. Both confirm cost-flattening holds across pattern variants. The added 13 minutes is not the</text> | |
| 85 | + <text x="100" y="672" font-size="14" fill="#c8c8c8">helper (still mechanical) — it's the migration tooling growing to handle 173 references instead of ~22, and one wider sed-collision.</text> | |
| 86 | + </g> | |
| 87 | + | |
| 88 | + <!-- Watermark --> | |
| 89 | + <text x="1120" y="704" text-anchor="end" font-family="ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Consolas, monospace" font-size="12" fill="#5a5a5a">https://tdd.md</text> | |
| 90 | +</svg> | |
src/a31_blog.ts
+6
−0
| @@ -12,6 +12,12 @@ export interface BlogEntry { | ||
| 12 | 12 | } |
| 13 | 13 | |
| 14 | 14 | export const ALL_POSTS: BlogEntry[] = [ |
| 15 | + { | |
| 16 | + slug: "sama-v2-portability-boundary-found", | |
| 17 | + title: "21 minutes 23 seconds — the portability boundary is empirically located", | |
| 18 | + description: "Third datapoint on the cost-flattening empirical chain. PR #42 (an evening), PR #53 (8m 8s, fixed-enum), PR #55 (21m 23s, data-driven). The second postmortem predicted ≤30 min for data-driven — this one measures it at 21m 23s, on the faster side of the predicted band. Three datapoints now align with a mechanical model: fixed-enum refactors land in ~8 min dominated by deploy time; data-driven refactors land in ~21 min because the migration tooling grows from a one-liner sed to a ~50-LOC Bun script, plus a spoof guard, plus wider over-rewrite recovery (the same pattern-risk as PR #53 but bigger surface). The helper itself stays mechanical: 13 lines for fixed-enum, 24 lines for data-driven (the added 11 being the ALL_POSTS lookup + date.slice). The Layer-3 wrapper stays byte-identical across all three. The pattern is reusable for data-driven URLs too; the cost grows with migration surface but stays bounded. Specific breakdown of the 21:23: ~10 min on new code (helper + sibling test + handler + spoof guard + Bun route + sitemap + blog index + edit-resolve), ~6 min on migration script + run, ~3 min recovering from over-rewrites + missed root-level CONTRIBUTING.md, ~2 min on PR + deploy. The 'new code' time was identical to PR #53; the difference was everything around it. The §5 chain now has three deltas confirming a model that's bounded across pattern variants. Two falsifiable next-tests: fourth fixed-enum refactor in the same band (≤10 min), data-driven with ~500-reference surface in ≤45 min.", | |
| 19 | + date: "2026-05-25", | |
| 20 | + }, | |
| 15 | 21 | { |
| 16 | 22 | slug: "sama-v2-second-url-refactor-postmortem", |
| 17 | 23 | title: "8 minutes 8 seconds — the cost-flattening hypothesis is confirmed", |
src/a31_goals.ts
+10
−0
| @@ -38,6 +38,16 @@ export interface GoalEntry { | ||
| 38 | 38 | } |
| 39 | 39 | |
| 40 | 40 | export const ALL_GOALS: GoalEntry[] = [ |
| 41 | + { | |
| 42 | + slug: "blog-date-prefix", | |
| 43 | + title: "Move /blog/<slug> → /blog/<yyyy-mm>/<slug> — data-driven portability test", | |
| 44 | + date: "2026-05-25", | |
| 45 | + branch: "blog-date-prefix", | |
| 46 | + prNumber: 55, | |
| 47 | + mergeSha: "72919e8", | |
| 48 | + status: "shipped", | |
| 49 | + relatedPosts: ["sama-v2-second-url-refactor-postmortem"], | |
| 50 | + }, | |
| 41 | 51 | { |
| 42 | 52 | slug: "sama-discipline-prefix", |
| 43 | 53 | title: "Move /sama/<discipline> → /sama/discipline/<slug> — hypothesis test", |