nickna / nickna/SharpTS

Split EmittedRuntime metadata into cohesive feature components

Open
#1,599 0 comments 0 reactions 0 assignees View on GitHub
tech-debt
Dominant language
C#
Stars
154
Forks
4
Avg merge
2h 46m
Merged PRs (30d)
189

Description

`EmittedRuntime` still holds substantial flat mutable metadata initialized with `null!`. Callers of that remaining surface must implicitly know which features and emission phases have initialized each handle. Optional features and forward declarations are legitimate requirements; this refactor makes their ownership and lifecycle explicit.

**Status: partially complete. Keep this issue open as the umbrella tracker for the remaining migrations.** Completed migrations through #1677 are merged. String coercion metadata is implemented in #1678; all local verification passed, and CI/review/merge continue. Work continues incrementally through the remaining families and the final residual-state audit.

Progress verified against `main` at [`8fe0c544`](https://github.com/nickna/SharpTS/commit/8fe0c5442a81a6cc2db8a71fa8b7d73534a983d5). See the [current holder](https://github.com/nickna/SharpTS/blob/8fe0c5442a81a6cc2db8a71fa8b7d73534a983d5/src/SharpTS/Compilation/EmittedRuntime.cs), [emission orchestration](https://github.com/nickna/SharpTS/blob/8fe0c5442a81a6cc2db8a71fa8b7d73534a983d5/src/SharpTS/Compilation/RuntimeEmitter.cs), and [documented migration pattern](https://github.com/nickna/SharpTS/blob/8fe0c5442a81a6cc2db8a71fa8b7d73534a983d5/ARCHITECTURE.md#runtime-metadata-components). The original audit referenced [this earlier holder snapshot](https://github.com/nickna/SharpTS/blob/0b4f96592c1b9379de4ca5a52a2e8968af0fe365/src/SharpTS/Compilation/EmittedRuntime.cs#L18).

## Completed

- [x] Establish and document a consistent component lifecycle: explicit optional availability, checked declaration access, forward references before body emission, and a completion boundary that validates handles and rejects subsequent writes.
- [x] DNS: `EmittedDnsRuntime`, including the promise-wrapper registry. Merged in #1605.
- [x] Zlib: `EmittedZlibRuntime`, including compression and streaming handles. Merged in #1608.
- [x] TLS: `EmittedTlsRuntime`, including module/socket metadata and the deferred connect handle. Merged in #1610.
- [x] Datagram/UDP: `EmittedDgramRuntime`, including deferred receive and message-closure handles. Merged in #1620.
- [x] TCP/IPC networking: `EmittedNetRuntime`, including socket/server, factory, and BlockList metadata. Merged in #1624.
- [x] Promise: `EmittedPromiseRuntime`, including 77 type, capability, combinator, prototype, adoption, resolving-callback, and reaction handles. Merged in #1634. Shared job scheduling and feature-specific Promise APIs remain with their owning infrastructure/families.
- [x] Array storage: required `EmittedArrayStorageRuntime`, including 47 declarations for array/hole types, constructors, sparse/packed-double accessors, rest builders, and numeric/boolean queues. Merged in #1635.
- [x] Array operations: required `EmittedArrayOperationsRuntime`, including 108 checked declarations replacing 109 flat properties, prototype/bound-method dispatch, live iterators, and consolidated receiver context. Merged in #1636.
- [x] Node crypto: optional `EmittedCryptoRuntime`, including 105 declarations for constructors, module helpers, digest/encoding primitives, scrypt, signing, DH/ECDH, KeyObject, and X509. Merged in #1637.
- [x] WebCrypto: required singleton accessor plus 49 optional implementation declarations, with checked availability and completion. Merged in #1638.
- [x] HTTP module/server: optional `EmittedHttpRuntime`, including 47 factories, utilities, agent helpers, server/request/response declarations, and deferred accept-worker/closure handles. Merged in #1639.
- [x] Fetch/Web API: required global cache field, 31 optional Web API declarations, and 15 optional client/dispatch/cache/cookie declarations, with checked availability and completion. Merged in #1640.
- [x] Node Buffer: optional `EmittedBufferRuntime`, including 79 checked declarations with explicit Buffer/typed-copy availability and completion. Merged in #1641.

- [x] ArrayBuffer: `EmittedArrayBufferRuntime`. Merged in #1642.
- [x] SharedArrayBuffer: `EmittedSharedArrayBufferRuntime`. Merged in #1643.
- [x] DataView: `EmittedDataViewRuntime`. Merged in #1644.
- [x] TypedArray: checked detection, storage, and operation metadata. Merged in #1645.
- [x] EventEmitter: `EmittedEventEmitterRuntime`. Merged in #1646.
- [x] Timers, timer Promise APIs, and microtasks: checked component ownership and completion. Merged in #1647.
- [x] Event loop and hosted hooks: `EmittedEventLoopRuntime` and hosted metadata. Merged in #1648.
- [x] Node streams: `EmittedNodeStreamRuntime`. Merged in #1649.
- [x] Web streams: `EmittedWebStreamRuntime`, including the peer field-access IL-verifier correction. Merged in #1650.
- [x] Filesystem data types and synchronous I/O: `EmittedFileSystemRuntime`. Merged in #1651.
- [x] Filesystem async operations and Promise-wrapper registry: `EmittedFileSystemAsyncRuntime`. Merged in #1652.
- [x] Filesystem streams: `EmittedFileSystemStreamRuntime`, including 22 declarations and explicit read/write constructors. Merged in #1653 after all checks and review passed; 75 focused and 7,408 broad regression tests passed, with eight baseline/IL-verification probes preserving all 17,994 method bodies.

- [x] Filesystem watchers and polling closures: `EmittedFileSystemWatcherRuntime`, including 31 checked declarations and 13 narrowed helpers. Merged in #1654 after all CI gates and review passed; 84 focused and 7,476 broad regression tests passed (two existing Windows HTTP skips). Eight IL-verified probes preserve normalized metadata and all 17,956 method bodies/exception regions.

- [x] Process: required `EmittedProcessRuntime` plus optional stream and hosted components, including 78 checked declarations and 27 narrowed helpers. Merged in #1655 after all CI gates and review passed; 329 focused and 7,594 broad regression tests passed (two existing Windows HTTP skips). Eleven IL-verified probes preserve normalized metadata, literals/constants, native imports, and all 12,824 method bodies/exception regions.

- [x] Child process: optional `EmittedChildProcessRuntime` owns 58 emitted declarations and 12 family-specific BCL references, with 28 narrowed helpers. Merged in #1656 after all CI gates and review passed; 329 focused and 7,697 broad regression tests passed (two existing Windows HTTP skips). Twelve IL-verified probes preserve normalized metadata, literals/constants, native imports, and all 16,018 method bodies/exception regions.

- [x] OS: optional `EmittedOsRuntime` owns three checked declarations, with four narrowed helpers. Merged in #1657 after all CI gates and review passed; 207 focused tests passed, including 25 new cases. Six IL-verified probes preserve normalized metadata, literals/constants, native imports, and all 6,513 method bodies/exception regions.

- [x] Console: required `EmittedConsoleRuntime` owns 32 checked declarations, with ten narrowed emission helpers and six shared call helpers. Merged in #1658 after all CI gates and review passed; 487 focused tests and 184 additional suspension tests passed, including 53 new cases. Ten IL-verified probes preserve normalized metadata, literals/constants, native imports, and all 11,615 method bodies/exception regions.

- [x] Inspection: required `EmittedInspectionRuntime` owns three checked declarations. Five inspection helpers and console.dir accept explicit component dependencies. Merged in #1659 after all CI gates and review passed; 415 focused tests passed, including 19 new cases. Six IL-verified probes preserve normalized metadata and all 7,576 method bodies/exception regions, with four exact standalone outputs and two hosted assemblies.

- [x] Text encoding: optional `EmittedTextEncodingRuntime` owns seven checked declarations, with three narrowed helpers and explicit constructor/global/invocation consumers. Merged in #1660 after all CI gates and review passed; 356 focused tests passed, including 30 new cases. Ten IL-verified probes preserve normalized metadata and all 13,019 method bodies/exception regions, with eight exact standalone outputs and two hosted assemblies.

- [x] Readline: optional `EmittedReadlineRuntime` owns seven checked declarations, including four former emitter fields, with thirteen narrowed helpers. Merged in #1661 after all CI gates and review passed; 377 regression cases covered, including 32 new cases. Nine IL-verified probes preserve normalized metadata and all 10,765 method bodies/exception regions, with seven exact standalone input/output cases and two hosted assemblies.

- [x] Module loading: required `EmittedModuleRuntime` with optional CommonJS and dynamic-import components owns fourteen declarations, replacing seven flat properties and seven emitter fields; ten helpers use explicit components. Merged in #1662 after all CI gates and review passed; 524 regression cases covered, including 42 new cases, plus both hosted top-level-await/import modes. Nine IL-verified probes preserve normalized metadata and all 9,900 method bodies/exception regions, with seven exact standalone outputs and two hosted assemblies.

- [x] VM: optional `EmittedVmRuntime` owns twelve checked declarations; thirteen helpers use explicit components and eight callable-registration points remain orchestration-owned. Merged in #1663 after all CI gates and review passed; all 492 regressions passed, including 36 new cases. Eleven IL-verified probes preserve normalized metadata and all 12,712 method bodies/exception regions, with nine exact executable outputs and two hosted assemblies.

- [x] Source execution: optional `EmittedSourceExecutionRuntime` owns two checked bridge declarations; its emitter receives the component and an orchestration-owned callback preserving both early registration points. Merged in #1664 after all CI gates and review passed; all 366 regressions passed, including 25 new cases. Eleven IL-verified probes preserve normalized metadata and all 12,960 method bodies/exception regions, with nine exact executable outputs and two hosted assemblies.

- [x] AbortController/AbortSignal: optional `EmittedAbortRuntime` owns nineteen checked declarations; sixteen Abort helpers and the generic namespace wrapper receive explicit dependencies. Merged in #1665 after all CI gates and review passed; all 771 focused regressions passed, including 52 new cases. Fourteen IL-verified probes preserve normalized metadata and all 15,935 method bodies/exception regions, with twelve exact executable outputs and two hosted assemblies.

- [x] AsyncLocalStorage: optional `EmittedAsyncLocalStorageRuntime` owns its constructor declaration; four helpers receive explicit component and function dependencies. Merged in #1666 after all CI gates and review passed; all 571 regression cases covered, including 29 new cases. Eleven IL-verified probes preserve normalized metadata and all 12,241 method bodies/exception regions, with nine exact standalone executions and two hosted assemblies. The primitive-import review finding was reproduced as an existing resolver rejection before code generation.

- [x] Intl: optional `EmittedIntlRuntime` owns ten factory and namespace declarations with checked early/factory/population stages; factory and shared namespace helpers receive explicit dependencies. Merged in #1667 after all CI gates and review passed; all 671 regressions covered, including 38 new cases. Eleven IL-verified probes preserve normalized metadata and all 11,908 method bodies/exception regions, with nine exact executions and two hosted assemblies.

- [x] Performance and TTY: separate optional components own checked declarations with independent availability and three narrowed helpers. Merged in #1668 after all CI gates and review passed; all 449 regressions passed, including 33 new cases. Eleven IL-verified probes preserve normalized metadata and all 13,076 method bodies/exception regions, with nine exact executions and two hosted assemblies. Lazy clocks, terminal descriptor coercion and redirected-stream behavior are unchanged.

- [x] Node error metadata: required `EmittedNodeErrorRuntime` owns six checked cross-phase declarations; four construction fields are local and fifteen helpers use explicit dependencies. Merged in #1669 after all CI gates and review passed; all 693 regressions passed, including 28 new cases. Twelve IL-verified probes preserve normalized metadata and all 26,394 method bodies/exception regions, with ten exact executions and two hosted assemblies. Error formatting, optional metadata, exception-data markers and I/O mappings remain unchanged.

- [x] Atomics: optional `EmittedAtomicsRuntime` owns fifteen checked declarations; five private helpers are local and twenty-one boundaries use explicit dependencies. Merged in #1670 after all CI gates and review passed. Validation covers all 655 regressions, including 47 new cases, with the two corrected feature-gate expectations reverified. Fourteen IL-verified probes preserve normalized metadata and all 17,555 method bodies/exception regions, with twelve exact executions and two hosted assemblies. Existing coercion, locking, inlining, Unsafe roots and wait/notify behavior are unchanged.

- [x] Cluster: optional `EmittedClusterRuntime` owns two checked declarations; three helpers and three module call sites use explicit dependencies. Merged in #1671 after all CI gates and review passed. All 368 regressions passed, including 28 new cases. Twelve IL-verified probes preserve normalized metadata and all 12,650 method bodies/exception regions, with ten exact executions and two hosted assemblies. Entry-script configuration, worker event-loop delegates, late-bound bridge behavior and deployment remain unchanged.

- [x] MessageChannel and MessagePort: required checked owners hold seventeen distinct declarations, validating both groups before freezing either; thirteen helpers and deferred worker receive emission use explicit dependencies. Merged in #1672 after all CI gates and review passed. All 567 regressions passed, including 46 new cases. Fifteen IL-verified probes preserve normalized metadata and all 16,013 method bodies/exception regions, with thirteen exact executions and two hosted assemblies. Cross-thread references, queue ordering, notification visibility, clone isolation and deployment remain unchanged.

- [x] Worker: required checked owner holds nine method declarations and two receive-cache fields, replacing ten flat properties and three emitter fields; four helpers use explicit dependencies. Merged in #1673 after all CI gates and review passed. Verification covers all 563 regressions, including 37 new cases; two initial full-feature expectations were narrowed to worker deployment reasons and all 25 component cases re-passed without production changes. Fifteen IL-verified probes preserve normalized metadata and all 16,239 method bodies/exception regions, with thirteen exact executions and two hosted assemblies. Deferred receive bodies, foreign caches, per-assembly context, environment cloning and deployment remain unchanged.

- [x] BroadcastChannel: optional checked owner holds thirteen declarations; twelve helpers use explicit dependencies. Seventeen emitter builders and two BCL caches are removed, with four unused method copies scoped locally. Merged in #1674 after all CI gates and review passed. All 492 regressions passed, including 42 new cases. Sixteen IL-verified probes preserve normalized metadata and all 17,043 method bodies/exception regions, with fourteen exact executions and two hosted assemblies. Registry lookup, clone/error isolation, queued delivery and event-loop references remain unchanged. CodeRabbit recorded exact-head coverage with no actionable findings but reported unavailable repository-clone analysis; supplemental local review inspected all changed production code and the existing lifecycle, feature, reuse and IL evidence without finding another issue.

- [x] Structured clone: required checked owner holds the clone wrapper and two clone-error declarations, preserving early exception and late wrapper completion. Two emitters use explicit dependencies and recursive construction stays local. Merged in #1675 after CI gates and review passed. All 685 regressions passed, including 47 new cases. Twenty-three IL-verified probes preserve normalized metadata and all 25,418 method bodies/exception regions, with twenty-one exact executions and two hosted assemblies. The initial foreign BCL Task rejection expectation was corrected against original behavior; actual same-assembly $Promise rejection is separately verified. Optional binary/Date/RegExp inputs, recursive copy behavior and ignored second argument are unchanged. Peer-family inputs and shared array adapters remain part of the final ownership audit. CodeRabbit recorded exact-head coverage with no actionable findings but again reported unavailable repository-clone analysis; supplemental local review and source comparison at the actual PR commit found no additional issue.

- [x] Core strings: required checked owner holds 44 declarations for core methods and their prototype; 36 emission boundaries use explicit dependencies. Merged in #1676 after CI gates and review passed. Verification covers 768 distinct passing cases, including 84 new cases; the new fixture reflection visibility was corrected and all 65 component plus 19 isolated cases re-passed. Twenty-two IL-verified comparisons preserve normalized metadata and all 22,633 method bodies/exception regions, with twenty exact executions and two hosted assemblies. Prototype shells/storage, typed signatures and optimization flags, parameter names, descriptors, function caches, mutable prototypes and optional RegExp inputs remain unchanged. Coercion, templates, boxed receivers and protocol dependencies remain separate scope. CodeRabbit recorded exact-head review coverage with no actionable findings but reported unavailable repository-clone analysis; supplemental local review and source comparison at the actual PR commit found no additional issue.

- [x] Templates and String.raw: required checked owner holds seven declarations for the created strings-list type, constructor/raw getter, concatenation and tag invocation; five emitters use explicit dependencies. Merged in #1677 after CI gates and review passed. Verification covers 462 distinct passing regressions, including 22 component and 15 isolated new cases. Eighteen IL-verified comparisons preserve normalized metadata and all 18,882 method bodies/exception regions, with sixteen exact executions and two hosted assemblies. Early creation, raw/cooked values, list freezing, receiver behavior, rest signatures, substitution/length normalization and evaluation order are unchanged. Guest TypeError tests inspect the existing thrown-value carrier. Probes use existing --noLib built-in typing because the original CLI declaration path rejects String.raw; the original computed-tag receiver behavior is preserved. Coercion, boxed receivers and other remaining ownership work stay in scope. CodeRabbit recorded exact-head coverage with no actionable findings but reported unavailable repository-clone analysis; supplemental local review and immutable-commit source comparison found no additional issue.

These migrations remove the old flat properties, route appropriate consumers through the component, and include lifecycle and feature-gating tests. Their PRs record the relevant standalone-output and IL-verification coverage. Each PR explicitly left this issue open for subsequent families.

Related completed cleanup: #1628 closed #1618 by removing nine write-only holder properties. That cleanup reduces the shared surface but does not complete the ownership migration.

## Current phase: String coercion metadata

PR #1678 is open at head `edd963f300ed2d69bdc64f7a5e92e86489981c48`, based on the template phase's verified merge `8fe0c544`. Required `EmittedStringCoercionRuntime` owns five declarations: Stringify, ToJsString, String(value), implicit StringifyCoerce and typed integer concatenation. Five emitter bodies and direct/runtime/async/generator/class consumers use the component and explicit dependencies. The three forward declarations keep their distinct early positions. ToJsString receives array components and scoped object/descriptor/function/symbol/global inputs, with the optional RegExp type retaining its orchestration gate. The scoped helper follows supplied nullable metadata; two regression cases prove independence from opposite emitter feature selections. Integer concatenation retains its typed signature, thread-static buffer, span formatting and optimization flags; construction-only handles remain local.

Release build and quality gates passed. All 736 regressions passed, including 32 new component and 22 isolated cases. Twenty-five IL-verified baseline/current assemblies preserve normalized metadata, imports, literals/constants and all 26,047 method bodies/exception regions; twenty-three execute with identical stdout/stderr/deployment and two validate hosted declarations. Declaration ordering is checked after serialization. Display formatting, language conversion, String(value)'s Symbol exemption, BigInt formatting, coercion hooks, prototype overrides, guest errors and primitive results are unchanged. CI/review continue before merge. Primitive wrappers, numeric and all other remaining language families, plus the final metadata/emitter-state/registry audit remain in scope; number formatting and other peer declarations stay with their existing owners pending those phases.

## Remaining work

These are tracking groups. Choose cohesive boundaries and split larger groups into bounded PRs as implementation proceeds.

- [ ] Remaining platform metadata: audit residual platform construction state.
- [ ] Remaining language/runtime families: strings/numbers/math/BigInt, objects/property descriptors and Reflect, JSON, collections/weak references, symbols, Date, RegExp, errors, functions/invocation, and iterator/generator support. Include general iteration/destructuring, collection iterators, generic element/length/key access, coercion, static-member dispatch, and call-argument expansion left outside the completed array phases. Split these into cohesive families rather than one replacement holder.
- [ ] Audit all residual flat metadata, emitter-held construction state, and registries before closure. Migrate remaining feature-owned state; document ownership and initialization contracts for intentionally shared infrastructure. Include remaining Node crypto construction state and the registry/BCL/local-construction boundaries documented by every completed phase. The groups above are not a substitute for this final inventory.

Verified remaining ownership defect: on the saved post-Math baseline, reusing one `RuntimeEmitter` for JSON, a minimal program, then JSON again leaks a reference to the first generated assembly into the second JSON output; invoking its `JsonStringify` throws `FileNotFoundException`. First-compilation and fresh-emitter controls both produce the expected JSON without that reference. The JSON phase must give its cached helper declarations per-compilation ownership and verify repeated/absent/present emission and standalone isolation. This defect remains unfinished scope here.

Final-audit preparation on the verified prepared post-Math source also identified eight write-only metadata stores: `RuntimeEmitter._getJsonShapeTableMethod`; `EmittedRuntime` SymbolPrototypeToString/ValueOf, RegExpTest/GetLastIndex/SetLastIndex, and RequireIteratorObject/InvokeIteratorNextWithSent. The full Release compiler source-symbol scan includes generated sources and has no compilation errors or unresolved candidates. Remove redundant storage in the corresponding JSON, Symbol, RegExp and iterator phases after checking other-project/reflection consumers. Preserve the generated helper definitions, local references and emitted IL; these findings are not permission to delete runtime methods. The construction ledger still has 393 outstanding field dispositions (350 metadata-typed), and the separate flat-property/registry audit remains required. These counts describe the prepared post-Math source, not completed migrations on main.

Final-audit refresh after the StringCoercion dependency correction: prepared Math tree `0b667fc0860f0b62250eb5cbd64f8e1e84c6817f` retains all 1,160 declaration records and 25 collection records from the preceding audit. Binding the same 1,234 source files plus 70 generated files finds 39,846 references, with zero errors, unresolved candidates or disabled regions. The only reference removed is the scoped ToJsString helper's hidden feature-state read. This refresh closes no additional ownership family or final-audit row; original baseline provenance and the JSON emitter-reuse output defect remain in scope.

Additional required scoped-dependency follow-ups from that audit: BoxedPrimitives must use its supplied optional BigInt/Date metadata before publication; the final cleanup must also make AbortSignalStaticAny's fine-grained soft-deployment selection explicit, remove ReadlineMethods' redundant hidden gate under its already-guarded required component contract, and make IsTypedArray's required detection helper follow optional implementation availability. Preserve the existing feature gates, absent-path behavior, method order and deployment rules, and verify opposite selection/input cases and generated output. These are dependency-contract findings, not demonstrated guest-output defects.

## Acceptance criteria for each migration

- Group metadata into a cohesive component and make consumers depend on that component instead of the entire mutable holder where practical.
- Represent optional feature availability explicitly and provide clear initialization/phase checks at the appropriate boundary.
- Preserve forward-declaration and body-emission phases, including references needed before method bodies are emitted.
- Follow and extend the documented incremental migration pattern.
- Remove migrated flat properties and duplicate handle storage instead of retaining permanent parallel sources of truth.
- Verify feature-present, feature-absent/tree-shaken, standalone output, and relevant IL-verification cases.
- Preserve compiled behavior, output dependency rules, and existing optimization performance characteristics.

A file split alone is insufficient: the intended outcome is cohesive ownership and an explicit initialization contract. Keep interpreter/compiler architecture changes out of this work. Estimated remaining effort: high; use incremental pull requests rather than a repository-wide rewrite.

## Closure rule

Keep this issue open while unfinished scope is tracked only here. Close it when the migration and residual-state audit are complete, or when every deferred item has explicit, linked follow-up tracking and the scope transfer is recorded here. Completing another individual family is progress toward this issue, not grounds to close the umbrella tracker.

Contributor guide

Open the contributing guide

Research direction

Start with src/SharpTS/Compilation/EmittedRuntime.cs and src/SharpTS/Compilation/RuntimeEmitter.cs, then read the documented migration pattern in ARCHITECTURE.md. Review the remaining metadata families and residual state against the completed migration list. Done means the remaining migrations and final residual-state audit are complete with the documented lifecycle checks preserved.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
compilers
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.