Skip to content

Commit 8558334

Browse files
committed
docs(spec): quote the entry split's byte readings from its merge base
Claude-Session: https://claude.ai/code/session_014EJ1ED8X4MMrT18BhVx4tx Co-authored-by: Claude <noreply@anthropic.com>
1 parent d418e55 commit 8558334

4 files changed

Lines changed: 13 additions & 13 deletions

File tree

‎.changeset/20646-migrations-entry-split.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ feat(spec)!: the ADR-0087 migration chain leaves the package root for the new `@
88

99
A `major`-class change — an existing import path stops resolving for these names — recorded as `minor` under the launch-window convention.
1010

11-
**Why.** The migration registry is mostly the guidance text `objectstack migrate meta` prints, and the root re-exported it. The registry does work when its module loads (the list of majors and each step's rationale are computed then), so no bundler could prove it unused, and all of that text rode in every bundle of the root, whatever the consumer imported. This is the source-side payback of the Studio console's first-screen ceiling raise that the maintainer ruled on the 17.5.0 upgrade. Measured on the splitting PR (tsup build, gzip -9):
11+
**Why.** The migration registry is mostly the guidance text `objectstack migrate meta` prints, and the root re-exported it. The registry does work when its module loads (the list of majors and each step's rationale are computed then), so no bundler could prove it unused, and all of that text rode in every bundle of the root, whatever the consumer imported. This is the source-side payback of the Studio console's first-screen ceiling raise that the maintainer ruled on the 17.5.0 upgrade. Measured on the splitting PR against its merge base `1a75e39d4a` (tsup build, gzip -9):
1212

1313
| | before | after |
1414
| --- | --- | --- |
15-
| `dist/index.js` (CommonJS root) | 3,775,445 B / 1,066,456 B gzip | 2,008,899 B / 565,285 B gzip |
16-
| `dist/browser/index.mjs` (the ESM root a browser bundler pulls) | 3,759,705 B / 1,064,775 B gzip | 1,993,837 B / 563,676 B gzip |
17-
| a browser bundle of the ten names the Studio console imports from the root (rolldown, minified) | 700,438 B gzip | 301,204 B gzip |
15+
| `dist/index.js` (CommonJS root) | 3,780,033 B / 1,067,061 B gzip | 2,009,810 B / 565,386 B gzip |
16+
| `dist/browser/index.mjs` (the ESM root a browser bundler pulls) | 3,764,293 B / 1,065,388 B gzip | 1,994,748 B / 563,787 B gzip |
17+
| a browser bundle of the ten names the Studio console imports from the root (rolldown, minified) | 700,884 B gzip | 301,287 B gzip |
1818

1919
The ADR-0087 **conversion layer stays on the root**: `defineStack` and `normalizeStackInput` read it at run time, so its names (`ALL_CONVERSIONS`, `CONVERSIONS_BY_MAJOR`, `applyConversions`, `applyConversionsToFlow`, `applyConversionsToStoredItem`, `collectConversionNotices`, the `CONVERSION_*_CODE` constants and their types) import from `@objectstack/spec` exactly as before.
2020

‎packages/spec/src/migrations/entries/semantic/18.migrations-entry-split.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,11 +38,11 @@ export const entry: SemanticMigration = {
3838
+ '`objectstack migrate meta` prints, and the package root re-exported it. The registry does work '
3939
+ 'when its module loads (the list of majors and each step\'s rationale are computed then), so no '
4040
+ 'bundler could prove it unused, and all of that text rode in every bundle of the root, whatever '
41-
+ 'the consumer imported: 1,758,310 of the root ESM bundle\'s 3,761,633 bytes. With the chain on '
42-
+ 'its own subpath the CommonJS root is 2,008,899 bytes instead of 3,775,445, and a browser bundle '
43-
+ 'of the ten names the Studio console imports from the root drops from 700,438 to 301,204 bytes '
41+
+ 'the consumer imported: 1,761,987 of the root ESM bundle\'s 3,766,221 bytes. With the chain on '
42+
+ 'its own subpath the CommonJS root is 2,009,810 bytes instead of 3,780,033, and a browser bundle '
43+
+ 'of the ten names the Studio console imports from the root drops from 700,884 to 301,287 bytes '
4444
+ 'gzipped. The conversion layer does not move: `defineStack` and `normalizeStackInput` read it '
45-
+ 'at run time, so moving its names would narrow the root and shrink it by 1,828 bytes. The split '
45+
+ 'at run time, so moving its names would narrow the root and shrink it by under two kilobytes. The split '
4646
+ 'moves an import path, which is TypeScript source rather than metadata — nothing authors, '
4747
+ 'stores or parses it — so there is no source a D2 conversion could rewrite, and the move is '
4848
+ 'recorded here.',

‎packages/spec/src/migrations/registry.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13307,11 +13307,11 @@ const step18: MigrationStep = {
1330713307
+ '`objectstack migrate meta` prints, and the package root re-exported it. The registry does work '
1330813308
+ 'when its module loads (the list of majors and each step\'s rationale are computed then), so no '
1330913309
+ 'bundler could prove it unused, and all of that text rode in every bundle of the root, whatever '
13310-
+ 'the consumer imported: 1,758,310 of the root ESM bundle\'s 3,761,633 bytes. With the chain on '
13311-
+ 'its own subpath the CommonJS root is 2,008,899 bytes instead of 3,775,445, and a browser bundle '
13312-
+ 'of the ten names the Studio console imports from the root drops from 700,438 to 301,204 bytes '
13310+
+ 'the consumer imported: 1,761,987 of the root ESM bundle\'s 3,766,221 bytes. With the chain on '
13311+
+ 'its own subpath the CommonJS root is 2,009,810 bytes instead of 3,780,033, and a browser bundle '
13312+
+ 'of the ten names the Studio console imports from the root drops from 700,884 to 301,287 bytes '
1331313313
+ 'gzipped. The conversion layer does not move: `defineStack` and `normalizeStackInput` read it '
13314-
+ 'at run time, so moving its names would narrow the root and shrink it by 1,828 bytes. The split '
13314+
+ 'at run time, so moving its names would narrow the root and shrink it by under two kilobytes. The split '
1331513315
+ 'moves an import path, which is TypeScript source rather than metadata — nothing authors, '
1331613316
+ 'stores or parses it — so there is no source a D2 conversion could rewrite, and the move is '
1331713317
+ 'recorded here.',

‎packages/spec/src/root-entry-migrations-split.pin.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
* step's rationale are computed then). A consumer's bundler therefore cannot
1010
* prove it unused, so whichever entry's module graph reaches it carries ALL of
1111
* it into every bundle of that entry. While the root re-exported it, that was
12-
* 1,758,310 of the root ESM bundle's 3,761,633 bytes, downloaded by every
12+
* 1,761,987 of the root ESM bundle's 3,766,221 bytes, downloaded by every
1313
* browser first screen that imports any root name. It moved to its own subpath;
1414
* the conversion layer (ADR-0087 D2) stays on the root, because `defineStack` /
1515
* `normalizeStackInput` read it at run time.

0 commit comments

Comments
 (0)