Summary
Empirical session probe against gemma-4-31b-it (session memory: project_core_base_conventions.md) surfaced observations about our core — some with intentional rationale already baked in, some genuinely worth investigating.
Intentional patterns (not refactor candidates — need documentation in class JSDoc):
className / ntype on instance (not just static) — Chrome DevTools ergonomics: inspecting this in debugger shows className immediately without expanding the prototype chain. Deliberate choice, saves significant debugging time at framework scale.globalThis.Neo dual role (module export + global singleton) — single-registry architecture required for mixed-runtime (dist/production + dynamically-loaded dist/esm). Splitting would break the setupClass gatekeeper's "first-one-wins" guarantee.me = this pattern — tracked separately (see the me=this policy audit ticket).
Candidates worth investigating (with strict benchmarking gate):
Neo.setupClass as "god function" (~193 lines handling namespace gatekeeping + config merging + overwrite application + getter/setter generation + mixin application + singleton creation + class-hierarchy registration). Runs once per class at module load, but is hot at cold-start for any Neo.mjs app (hundreds to thousands of classes). Decomposition into internal helpers might help readability — but any such refactor must demonstrate zero cold-start regression + accounted GC pressure from intermediate objects.- Variable shadowing in
Neo.create — className reassigned from string / object / class constructor depending on input type. Cognitive tax for readers without TypeScript; possibly clearer as separate variables.
Audit scope — documentation + benchmarks, NOT refactor:
- The output of this ticket is (a) JSDoc additions capturing intentional rationale and (b) a baseline benchmark harness for hot paths. Any actual refactor becomes a follow-up ticket that must pass the A/B benchmark gate.
The Fix
- Add class-level JSDoc in
src/Neo.mjs explaining the globalThis.Neo single-registry architecture + the setupClass hot-path / GC-pressure constraint.
- Add class-level JSDoc in
src/core/Base.mjs explaining the className / ntype on-instance DevTools-ergonomics rationale.
- Add a
buildScripts/benchmarks/ harness (or extend existing) with a setupClass-cold-start.mjs micro-benchmark producing a baseline timing + memory profile. Baseline gets committed as reference for future refactor proposals to A/B against.
- File follow-up tickets ONLY for refactor candidates that demonstrate measurable improvement AND account for application-engine + agent-OS ripple.
Acceptance Criteria
Out of Scope
- Actual refactors (they become downstream tickets pending benchmark data).
me = this policy (separate ticket).- PR-comment hygiene rule (separate ticket).
Related
- Session memory:
project_core_base_conventions.md — historical rationale preservation
- Empirical probe origin: PR #10105 (capability probe against gemma-4-31b-it)
- Coding standards:
.github/CODING_GUIDELINES.md §35 (const economy, by extension applies to hot-path patterns)
Origin Session ID: 1db25bbe-f39d-4dcd-bb0e-bc125ce91326
Summary
Empirical session probe against
gemma-4-31b-it(session memory:project_core_base_conventions.md) surfaced observations about our core — some with intentional rationale already baked in, some genuinely worth investigating.Intentional patterns (not refactor candidates — need documentation in class JSDoc):
className/ntypeon instance (not just static) — Chrome DevTools ergonomics: inspectingthisin debugger shows className immediately without expanding the prototype chain. Deliberate choice, saves significant debugging time at framework scale.globalThis.Neodual role (module export + global singleton) — single-registry architecture required for mixed-runtime (dist/production + dynamically-loaded dist/esm). Splitting would break thesetupClassgatekeeper's "first-one-wins" guarantee.me = thispattern — tracked separately (see theme=thispolicy audit ticket).Candidates worth investigating (with strict benchmarking gate):
Neo.setupClassas "god function" (~193 lines handling namespace gatekeeping + config merging + overwrite application + getter/setter generation + mixin application + singleton creation + class-hierarchy registration). Runs once per class at module load, but is hot at cold-start for any Neo.mjs app (hundreds to thousands of classes). Decomposition into internal helpers might help readability — but any such refactor must demonstrate zero cold-start regression + accounted GC pressure from intermediate objects.Neo.create—classNamereassigned from string / object / class constructor depending on input type. Cognitive tax for readers without TypeScript; possibly clearer as separate variables.Audit scope — documentation + benchmarks, NOT refactor:
The Fix
src/Neo.mjsexplaining theglobalThis.Neosingle-registry architecture + thesetupClasshot-path / GC-pressure constraint.src/core/Base.mjsexplaining theclassName/ntypeon-instance DevTools-ergonomics rationale.buildScripts/benchmarks/harness (or extend existing) with asetupClass-cold-start.mjsmicro-benchmark producing a baseline timing + memory profile. Baseline gets committed as reference for future refactor proposals to A/B against.Acceptance Criteria
Neo.mjsclass-level JSDoc explainsglobalThis.Neosingle-registry +setupClasshot-path constraint with pointer to benchmark harnessBase.mjsclass-level JSDoc documentsclassName/ntypeon-instance DevTools rationalebuildScripts/benchmarks/setupClass-cold-start.mjs(or similar) produces reproducible baselineOut of Scope
me = thispolicy (separate ticket).Related
project_core_base_conventions.md— historical rationale preservation.github/CODING_GUIDELINES.md§35 (const economy, by extension applies to hot-path patterns)Origin Session ID: 1db25bbe-f39d-4dcd-bb0e-bc125ce91326