ADR 0007: the fuller +1.5 KB protocol cost (atom + collection waves)

Author: borkdude

doc/ai/adr/0007-deferred-core-fn-costs.md

@@ -11,26 +11,38 @@ defer, with the trigger that should reopen each.
 
 ### Protocol dispatch bundle cost
 
-The protocol layer (0.14.203) made the common core fns reference their protocol
-slot to dispatch to custom types: `assoc` names `IAssociative__assoc`, `conj`
+Protocol dispatch arrived in two waves, both pinning machinery into plain-data
+bundles.
+
+Wave 1, atoms (0.14.201): `IReset`/`ISwap`/`IWatchable`/`IAtom`/`IDeref` were
+added to `atom`/`swap!`/`reset!`/`deref`/`add-watch`. An app using plain atoms
+(`swap!`, `add-watch`, no custom `IAtom` type) pins the lot.
+
+Wave 2, collections (0.14.203-205): `assoc` names `IAssociative__assoc`, `conj`
 names `ICollection__conj`, `get` names `ILookup__lookup`, `=` names
-`IEquiv__equiv`, and so on. ADR 0006 and `symbol-pure-dce` shake out the slots an
-app does not use. But a broad app uses `assoc` and `conj` and `count` and `get`
-and `=` together, so the union of its fns references the whole slot set, plus
-`INSTANCE_TYPE`. That block is then pinned into the bundle.
+`IEquiv__equiv`, plus `INSTANCE_TYPE`. A broad app uses these together and pins
+the whole set. ADR 0006 and `symbol-pure-dce` shake out slots an app does not
+use; the union a real app references survives.
 
-Measured on the js-framework-benchmark reagami app (same compiled app, only the
-runtime core.js swapped):
+Measured with the js-framework-benchmark reagami app, a clean official
+`build-prod` per squint version (compiled and bundled entirely on each version,
+gzipped):
 
-| runtime | raw (min) | gzip |
+| squint | gzip | note |
 |---|---|---|
-| main | 25973 | 9197 |
-| 0.14.202 (pre-protocol) | 24136 | 8659 |
-| delta | +1837 | **+538** |
-
-reagami and the demo define no `deftype`/`defrecord`/`extend-type`, so for them
-the whole block is dead weight: it dispatches to custom impls that do not exist.
-This is true of most plain-data apps.
+| 0.14.197 | 7517 | before both waves |
+| 0.14.200 | 7705 | before atoms |
+| 0.14.201 | 8644 | +939, atom protocols |
+| 0.14.202 | 8648 | before collections |
+| 0.14.205 | 9520 | collection protocols, unfixed |
+| 0.14.206 | 9190 | collections, after symbol-pure-dce + plain-data (-330 vs 205) |
+
+Net, about 1.5 KB of the 9.0 KB shipping app (~17%) is protocol dispatch
+machinery: ~+939 atoms plus ~+542 collections. reagami and the demo define no
+`deftype`/`defrecord`/`extend-type`, so all of it is dead weight - it dispatches
+to custom impls that do not exist. (An earlier note swapped only the runtime
+core.js and reported +538; that captured the collection wave alone, undercounting
+the total by ~3x.)
 
 The fix is to invert the dispatch, like CLJS: base fns handle only native types
 (Object/Array/primitive/Map/Set) and name no protocol slot; `extend-type` and
@@ -59,10 +71,11 @@ doc/ai/ideas.md "Emit direct fixed-arity calls" idea.
 
 Defer both. Ship neither fix now.
 
-- The protocol bundle cost is ~1/2 KB gzip per broad plain-data app. Recovering
-  it means reworking the protocol system that landed weeks ago, with regression
-  risk to records, transients and `extend-type`. The trade does not clear the bar
-  today.
+- The protocol bundle cost is ~1.5 KB gzip (~17% of the shipping app), in two
+  waves. At that size the win clearly justifies the work; what defers it is
+  risk, not payoff. Recovering it means reworking the protocol system that
+  landed weeks ago, with regression risk to records, transients and
+  `extend-type`. Do it once that code has settled, not against fresh code.
 - The variadic runtime patch was tried in #961 and dropped: a 2-arg `min`/`max`
   arity that node cannot show a win for and that Chrome does not benefit from. The
   real fix is the compiler-level per-arity emission, which is larger.
@@ -72,15 +85,16 @@ Defer both. Ship neither fix now.
 - `bb test:size` runs in CI (this ADR's companion change), so the protocol cost
   is visible per commit and a regression past the threshold fails the build.
 - reagami sidesteps the `min` cost with `js/Math.min` and does not depend on
-  either fix. It stays current with squint and pays the ~1/2 KB, still the
+  either fix. It stays current with squint and pays the ~1.5 KB, still the
   smallest app in the benchmark table.
 - Both fixes remain open, documented with measurements, ready to execute.
 
 ## When to revisit
 
-- Protocol bundle cost: when `test:size` shows the tax crossing a threshold that
-  matters, or a size-sensitive consumer is blocked by it - by then the protocol
-  code is battle-tested and the inversion is far less risky than doing it now
-  against fresh code.
+- Protocol bundle cost: the ~17% is already a size that matters, so the gate is
+  not the payoff but the protocol code settling. Revisit once records,
+  transients and `extend-type` have proven stable in the wild, or sooner if a
+  size-sensitive consumer is blocked. `test:size` keeps the number honest
+  meanwhile.
 - Variadic call cost: alongside the fixed-arity codegen work in doc/ai/ideas.md,
   which supersedes the reverted runtime patch.