ADR 0007: POC, decision matrix, and the breaking-ABI blocker

Author: borkdude

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

@@ -44,13 +44,13 @@ 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
-`deftype`/`defrecord` install the dispatch. An app with no protocol impls pulls
-zero protocol machinery. The DCE-clean mechanism is for `extend-type` to wrap the
-affected core fns, so the base fn holds no protocol reference to retain. The
-binding constraint is that ESM imports are read-only, so the fns need a mutable
-holder or a registry indirection.
+The fix inverts the dispatch, like CLJS: base fns handle native types
+(Object/Array/primitive/Map/Set) inline and name no protocol slot; built-in
+branded types (records, sorted collections, atoms) dispatch by brand; a
+constructor registry, populated by `extend-type`/`deftype`/`defrecord`, is
+consulted only for the remaining non-native types. An app with no protocol
+impls pulls zero protocol machinery. A proof of concept (doc/ai/adr/0007-poc/)
+validated this, ruled out one alternative on perf, and surfaced one blocker.
 
 ### Variadic call-site cost
 
@@ -67,15 +67,70 @@ analysis both succeed, and in throttled Chrome they did not (a fast-arity runtim
 #887 reverted it (double-evaluation); per-arity functions avoid that. This is the
 doc/ai/ideas.md "Emit direct fixed-arity calls" idea.
 
+## Proof of concept
+
+Three standalone experiments in doc/ai/adr/0007-poc/ (run with `node`), modelling
+`get`:
+
+- perf.cjs - the plain-data hot path is flat (~1x baseline) for the protocol-free
+  base. But the naive "wrap the fn" mechanism regresses 2.4x the moment any
+  `extend-type` exists, because every call then threads the wrapper (and it
+  compounds per extension). A registry the base consults only for non-native
+  types stays flat in both cases.
+- dce.cjs - with a base that names no slot, a plain-data app bundle drops every
+  protocol symbol (12 -> 0 in the model) and shrinks. Conditional: built-in
+  types must not be eager-registered (`registry.set(T, ...)` at top level is a
+  side effect that pins T into every bundle), so they stay brand-dispatched.
+- extend.cjs - a user can extend their own type to a built-in protocol (works via
+  the registry). Overriding a native type is ignored (the inline path wins) -
+  which is already true in today's squint, so no regression.
+
+Decision matrix (++ good, -- deal-breaker, ~ caveat; squint down each column):
+
+| criterion                    | baseline (slots) | protocol-free | wrapping | registry (hybrid) |
+|------------------------------|:----------------:|:-------------:|:--------:|:-----------------:|
+| hot path, plain data         |        ++        |      ++       |    ++    |        ++         |
+| hot path, extends present    |        ++        |      ++       |  **--**  |        ++         |
+| DCE: slot symbols shake out  |      **--**      |      ++       |    ++    |        ++         |
+| runtime-extensible           |        ++        |    **--**     |    ++    |        ++         |
+| backward-compatible ABI      |        ++        |    **--**     |  **--**  |      **--**       |
+| built-in types DCE cleanly   |        ++        |      ~        |    ~     |         ~         |
+
+Reading the columns: baseline fails only DCE (the whole reason for this ADR);
+protocol-free and wrapping each carry two deal-breakers; the registry hybrid
+carries exactly one - the ABI break - and that break is shared by *every* option
+that recovers DCE. So the matrix collapses to a single trade: **DCE win vs ABI
+stability**. Every row-pair has one and only one `++`; you cannot have both.
+Among the mechanisms that do fix DCE, registry is strictly best.
+
+## The blocker: it is a breaking ABI change
+
+The mechanism moves protocol dispatch from prototype slots to a registry, so it
+changes the contract between compiled code and core.js. `extend-type`/`deftype`/
+`defrecord` would emit registry calls instead of `prototype[SLOT] = fn`, and core
+fns would consult the registry instead of `coll[SLOT]`. Consequences:
+
+- Code compiled by an older squint (slot-style) run against a newer registry
+  core.js has its protocol impls silently ignored, and vice versa. A pre-compiled
+  published library that uses protocols breaks against a mismatched core.js.
+- It cannot be made backward-compatible. Keeping a slot check in the base fns for
+  old code re-references the slot symbol, which pins it, which forfeits the entire
+  DCE win. DCE and slot-compat are mutually exclusive.
+
+So this is a breaking change requiring recompilation across the ecosystem, and it
+should be batched into a major version, not shipped in a point release. reagami
+itself is unaffected (it defines no protocols), but the change is squint-wide.
+
 ## Decision
 
 Defer both. Ship neither fix now.
 
 - 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.
+  waves. The size clearly justifies the work and the POC found a viable,
+  perf-neutral mechanism (the registry hybrid; wrapping rejected on perf). What
+  defers it is not payoff: it is a breaking ABI change (above) that belongs in a
+  major version, plus the regression risk of reworking protocol code that landed
+  weeks ago. Do it in a deliberate breaking window, once that code has settled.
 - 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.
@@ -91,10 +146,11 @@ Defer both. Ship neither fix now.
 
 ## When to revisit
 
-- 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
+- Protocol bundle cost: the ~17% is already a size that matters, and the POC
+  de-risked the mechanism, so the gate is the ABI break. Revisit at the next
+  major/breaking-change window, once records, transients and `extend-type` have
+  proven stable in the wild - or sooner if a size-sensitive consumer is blocked
+  and a coordinated recompile is acceptable. `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.

doc/ai/adr/0007-poc/README.md

@@ -0,0 +1,12 @@
+# ADR 0007 proof of concept
+
+Standalone `node` experiments backing doc/ai/adr/0007-deferred-core-fn-costs.md.
+No build step; each is self-contained.
+
+- `perf.cjs` - hot-path perf of the dispatch mechanisms (`node perf.cjs`, or
+  `EXTENDED=1 node perf.cjs`). Shows the registry hybrid is perf-neutral and
+  wrapping regresses once an `extend-type` exists.
+- `dce.cjs` - whether a protocol-free base lets the slot symbols shake out of a
+  plain-data bundle (`node dce.cjs`; needs esbuild, this repo's devDep).
+- `extend.cjs` - whether a user can still extend a built-in protocol in the
+  registry model (`node extend.cjs`).

doc/ai/adr/0007-poc/dce.cjs

@@ -0,0 +1,46 @@
+// ADR 0007 POC - DCE. Does a protocol-free base actually let the slot symbols
+// shake out of a plain-data bundle? Generates a baseline core (fns name their
+// slot) and a registry core (fns name no slot), bundles a plain-data app that
+// uses several fns against each, and reports bytes + how many slot symbols
+// survive. Needs esbuild (this repo's devDep).
+//
+//   node dce.js
+
+const { buildSync } = require('esbuild');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'adr7-dce-'));
+const slots = ['ILookup', 'IAssoc', 'IColl', 'ICount', 'IMap', 'IEquiv', 'IIndexed', 'IReset', 'ISwap', 'IWatch', 'IDeref', 'IEmpty'];
+
+// baseline: 12 slot symbols; 5 fns each naming a few, so a broad app pins all 12
+let base = slots.map((s) => `export const ${s}__s = /* @__PURE__ */ Symbol('${s}_-s');`).join('\n') + '\n' +
+  `export function get(c,k,nf){ if(c==null)return nf; if(c.constructor===Object){const v=c[k];return v===undefined?nf:v;} if(c[ILookup__s]!==undefined)return c[ILookup__s](c,k,nf); if(c[IIndexed__s]!==undefined)return c[IIndexed__s](c,k); return nf; }
+export function assoc(c,k,v){ if(c[IAssoc__s]!==undefined)return c[IAssoc__s](c,k,v); if(c[IMap__s]!==undefined){} return {...c,[k]:v}; }
+export function conj(c,x){ if(c[IColl__s]!==undefined)return c[IColl__s](c,x); if(c[IEmpty__s]!==undefined){} return [...c,x]; }
+export function deref(a){ if(a[IDeref__s]!==undefined)return a[IDeref__s](a); return a.v; }
+export function swap(a,f){ if(a[ISwap__s]!==undefined)return a[ISwap__s](a,f); a.v=f(a.v); if(a[IWatch__s]!==undefined){} if(a[IReset__s]!==undefined){} if(a[IEquiv__s]!==undefined){} if(a[ICount__s]!==undefined){} return a.v; }`;
+
+// registry: same fns, native inline, no slot symbols; registry only for extend-type
+let reg = `const reg=new Map();
+function dispatch(p,c){ const m=reg.get(p); return m&&m.get(c.constructor); }
+export function extendType(p,T,fn){ (reg.get(p)||reg.set(p,new Map()).get(p)).set(T,fn); }
+export function get(c,k,nf){ if(c==null)return nf; if(c.constructor===Object){const v=c[k];return v===undefined?nf:v;} if(reg.size){const f=dispatch('lookup',c);if(f)return f(c,k,nf);} return nf; }
+export function assoc(c,k,v){ if(reg.size){const f=dispatch('assoc',c);if(f)return f(c,k,v);} return {...c,[k]:v}; }
+export function conj(c,x){ if(reg.size){const f=dispatch('coll',c);if(f)return f(c,x);} return [...c,x]; }
+export function deref(a){ if(reg.size){const f=dispatch('deref',a);if(f)return f(a);} return a.v; }
+export function swap(a,f){ if(reg.size){const g=dispatch('swap',a);if(g)return g(a,f);} a.v=f(a.v); return a.v; }`;
+
+fs.writeFileSync(path.join(dir, 'core-base.js'), base);
+fs.writeFileSync(path.join(dir, 'core-reg.js'), reg);
+const app = `import {get,assoc,conj,deref,swap} from CORE; const a={v:0}; console.log(get({x:1},'x'), assoc({},'k',1), conj([],1), deref(a), swap(a,n=>n+1));`;
+
+for (const [name, core] of [['baseline (slots)', 'core-base.js'], ['registry', 'core-reg.js']]) {
+  const entry = path.join(dir, 'app.js');
+  fs.writeFileSync(entry, app.replace('CORE', JSON.stringify('./' + core)));
+  const out = buildSync({ entryPoints: [entry], bundle: true, minify: true, format: 'esm', write: false, absWorkingDir: dir }).outputFiles[0].text;
+  const symbolsLeft = (out.match(/_-s/g) || []).length;
+  console.log(name.padEnd(18), 'bytes=' + out.length, ' slot-symbols-remaining=' + symbolsLeft);
+}
+fs.rmSync(dir, { recursive: true, force: true });

doc/ai/adr/0007-poc/extend.cjs

@@ -0,0 +1,30 @@
+// ADR 0007 POC - extensibility. In the registry model (base fn does native
+// dispatch inline, then consults a registry for non-native types), can a user
+// still extend a built-in protocol? Shows: yes for their own types; no for
+// native types - which matches current squint, where natives are fast-pathed
+// inline before any slot check.
+//
+//   node extend.js
+
+const reg = new Map(); // protocol -> (constructor -> impl)
+function extendType(proto, Type, fn) {
+  if (!reg.has(proto)) reg.set(proto, new Map());
+  reg.get(proto).set(Type, fn);
+}
+function get(coll, key, nf) {
+  if (coll == null) return nf;
+  if (coll.constructor === Object) { const v = coll[key]; return v === undefined ? nf : v; } // native inline
+  if (Array.isArray(coll))         { const v = coll[key]; return v === undefined ? nf : v; } // native inline
+  if (reg.size) { const m = reg.get('ILookup'); const f = m && m.get(coll.constructor); if (f) return f(coll, key, nf); }
+  return nf;
+}
+
+class RangeMap { constructor(lo, hi) { this.lo = lo; this.hi = hi; } }
+extendType('ILookup', RangeMap, (rm, k, nf) => (k >= rm.lo && k <= rm.hi ? k * 10 : nf)); // own type -> built-in protocol
+extendType('ILookup', Array, () => 'CUSTOM-ARRAY');                                         // native type -> built-in protocol
+
+const ok = (a, b, m) => console.log((a === b ? 'ok  ' : 'FAIL') + '  ' + m + '  => ' + a);
+ok(get(new RangeMap(1, 5), 3, 'nf'), 30, 'own type extends ILookup, hit');
+ok(get(new RangeMap(1, 5), 9, 'nf'), 'nf', 'own type extends ILookup, miss');
+ok(get([10, 20, 30], 1, 'nf'), 20, 'native Array: inline wins, extension ignored (as in current squint)');
+ok(get({ x: 1 }, 'x', 'nf'), 1, 'plain object: native inline, not overridable');

doc/ai/adr/0007-poc/perf.cjs

@@ -0,0 +1,83 @@
+// ADR 0007 POC - perf. Does making core fns protocol-free (so the slots DCE
+// out) slow the hot path? Models `get` four ways and benchmarks the common
+// case: read a key from a plain object.
+//
+// Each variant runs in its own process (spawned below) so it gets a clean,
+// monomorphic JIT - a single shared call site would go megamorphic and the
+// first variant measured would look artificially fast.
+//
+//   node perf.js              # run the interleaved benchmark
+//   EXTENDED=1 node perf.js   # simulate an unrelated extend-type in the app
+//   node perf.js <variant>    # (internal) benchmark one variant, print ns/op
+
+const ILookup__lookup = Symbol('ILookup_-lookup');
+
+function get_baseline(coll, key, nf) { // current squint: names the slot -> pins it
+  if (coll == null) return nf;
+  if (coll.constructor === Object) { const v = coll[key]; return v === undefined ? nf : v; }
+  if (Array.isArray(coll)) { const v = coll[key]; return v === undefined ? nf : v; }
+  if (coll instanceof Map) return coll.has(key) ? coll.get(key) : nf;
+  if (coll[ILookup__lookup] !== undefined) return coll[ILookup__lookup](coll, key, nf);
+  return nf;
+}
+function get_free(coll, key, nf) { // native only, no slot (not runtime-extensible)
+  if (coll == null) return nf;
+  if (coll.constructor === Object) { const v = coll[key]; return v === undefined ? nf : v; }
+  if (Array.isArray(coll)) { const v = coll[key]; return v === undefined ? nf : v; }
+  if (coll instanceof Map) return coll.has(key) ? coll.get(key) : nf;
+  return nf;
+}
+const holder = { get: (c, k, nf) => get_free(c, k, nf) }; // extend-type wraps holder.get
+function get_holder(coll, key, nf) { return holder.get(coll, key, nf); }
+const registry = new Map(); // constructor -> impl ; base consults it only for non-native
+function get_registry(coll, key, nf) {
+  if (coll == null) return nf;
+  if (coll.constructor === Object) { const v = coll[key]; return v === undefined ? nf : v; }
+  if (Array.isArray(coll)) { const v = coll[key]; return v === undefined ? nf : v; }
+  if (coll instanceof Map) return coll.has(key) ? coll.get(key) : nf;
+  if (registry.size) { const f = registry.get(coll.constructor); if (f) return f(coll, key, nf); }
+  return nf;
+}
+if (process.env.EXTENDED) { // an unrelated protocol extension exists somewhere in the app
+  class Other {}
+  const prev = holder.get;
+  holder.get = (c, k, nf) => (c instanceof Other ? nf : prev(c, k, nf));
+  registry.set(Other, (c, k, nf) => nf);
+}
+
+const objs = Array.from({ length: 1024 }, (_, i) => ({ id: i, label: 'row ' + i, selected: false }));
+
+function benchOne(V) {
+  const loop = (iters) => {
+    let s; const t0 = process.hrtime.bigint();
+    switch (V) {
+      case 'baseline': for (let i = 0; i < iters; i++) s = get_baseline(objs[i & 1023], 'label', null); break;
+      case 'free':     for (let i = 0; i < iters; i++) s = get_free(objs[i & 1023], 'label', null); break;
+      case 'holder':   for (let i = 0; i < iters; i++) s = get_holder(objs[i & 1023], 'label', null); break;
+      case 'registry': for (let i = 0; i < iters; i++) s = get_registry(objs[i & 1023], 'label', null); break;
+    }
+    globalThis.__sink = s;
+    return Number(process.hrtime.bigint() - t0) / iters;
+  };
+  loop(500000);
+  let best = Infinity;
+  for (let r = 0; r < 5; r++) best = Math.min(best, loop(3000000));
+  return best;
+}
+
+const NAMES = { baseline: 'baseline (inline slot)', free: 'protocol-free direct', holder: 'holder / wrapping', registry: 'registry guard' };
+
+if (process.argv[2]) { console.log(benchOne(process.argv[2]).toFixed(4)); process.exit(0); }
+
+const { execFileSync } = require('node:child_process');
+const ROUNDS = 9, samples = { baseline: [], free: [], holder: [], registry: [] };
+for (let r = 0; r < ROUNDS; r++)
+  for (const n of Object.keys(samples))
+    samples[n].push(parseFloat(execFileSync(process.execPath, [__filename, n], { encoding: 'utf8', env: process.env })));
+const median = (a) => [...a].sort((x, y) => x - y)[a.length >> 1];
+const base = median(samples.baseline);
+console.log(`get "label" from a plain object, median of ${ROUNDS} procs${process.env.EXTENDED ? ' (unrelated extend-type present)' : ''}:`);
+for (const n of Object.keys(samples)) {
+  const m = median(samples[n]);
+  console.log('  ' + NAMES[n].padEnd(24), m.toFixed(4), 'ns  ' + (m / base).toFixed(3) + 'x');
+}