Skip to content

Benchmark methodology and history ​

This archive preserves the original version-specific measurements, failed reviews, sampling methods and reproduction commands. Start with the current performance guide to evaluate Twill today. Historical absolute timings are not directly comparable across reports, and retired Rust results do not describe the current Node SDK.

Runtime behavior ​

Twill is a build-time syntax layer. Ordinary trailing closures become native arrow functions and guards become native branches. Those constructs introduce no runtime library. The benchmark checks that representative callback output matches equivalent handwritten JavaScript, and React/Vue component output matches equivalent native JSX after emission.

Single-expression component children are direct JSX values. General child collection uses a local array and ordered pushes; parameterized render props remain lazy callbacks. These have the costs of their emitted JavaScript and the selected framework.

In published 0.2.0, defer uses one callback and native finally for a single direct cleanup. Multiple or control-flow registrations use a lazy block-local stack with reverse-order draining. Both paths allocate cleanup closures; the dynamic path additionally allocates an array. Native try/finally remains useful for allocation-sensitive code. Explicit asynchronous cleanup adds the cost of awaiting cleanup.

Refinements in 0.3.0 ​

The current source removes repeated work in three places:

  • Eligible direct synchronous defer registrations become native nested try/finally, with no callback, stack or helper import. Later lexical/type or guard bindings, function hoisting, direct eval/with, this or definite-assignment-sensitive declarations, native disposal boundaries and cleanup-local function/var/strict behavior conservatively retain the existing path. Dynamic/async registration also keeps its semantics and costs.
  • Compiler tree walks avoid temporary property-pair arrays. Module compilation reuses parsed configuration for up to 64 source directories, still validating every dependency's contents and absent-file probes before reuse.
  • Editor diagnostics reuse the recovered transform and its first strict syntax error. VS Code caches text by document version; edits still synchronize complete overlays with native TS-server projects immediately. Transporting full snapshots and checking changed dependents remain real costs.

The refinement report compares an unchanged build at a8db852 with the source build on the same Linux x64 / Node 24.19 shared host. It retains three alternating pairs of isolated workers, all 15 timing samples per worker, source/output digests, build identities and generated cleanup code. Compiler/tool samples include high-resolution maps; runtime samples assert observable state. Cold uncached loader runs retain nine alternating pairs of fresh processes and execute an actual 100-import graph.

WorkloadBefore, medianSource refinement, medianPaired after / before
Transform 1,000 callbacks146.33 ms141.97 ms0.97×
Repeat unchanged editor diagnostics, 500 callbacks76.23 ms0.055 ms0.0007×
Edit then diagnose, 500 callbacks222.20 ms143.14 ms0.64×
Compile 100 modules with shared configuration191.65 ms155.46 ms0.82×
One direct cleanup, 100,000 invocations0.178 ms0.176 ms1.02×
Four direct cleanups, 100,000 invocations6.83 ms0.326 ms0.048×
100 dynamic captured-loop cleanups, 10,000 invocations21.34 ms20.84 ms0.97×
Cold uncached script with 100 imports1,180 ms1,110 ms0.95×

Worker medians and paired ratios are aggregated separately; dividing the two displayed medians need not equal the median paired ratio. Small timing differences and the cold-start result vary across runs. Dynamic-loop output is byte-identical before/after: its timing difference does not demonstrate a generated-code regression or improvement. Its natural reverse-loop reference remains about 13× faster in this fixture. Eligible one/four-cleanup minified output drops from 86/283 bytes to 66/144 bytes, matching the native reference exactly.

The static cleanup outputs match natural handwritten native try/finally after ordinary minification. A direct registration already approaches native speed; removing its callback mainly reduces output and allocation dependence. Multiple direct registrations benefit much more. Reusing an unchanged file's diagnostics does not represent end-to-end editor typing latency; edited diagnostics are measured separately. Configuration reuse saves repeated parsing, while cold initialization still loads Node/TypeScript/loader machinery.

Dynamic captured-loop cleanup still allocates and dispatches registrations and remains substantially slower than a native reverse loop doing just the same additions. Its retained closure/stack semantics are not interchangeable with that specialized loop for arbitrary programs. This refinement does not establish native parity for every construct, cold script or editor action. Profile real workloads; prebuilt/exported JavaScript remains the shortest startup path.

To reproduce, build the unchanged revision in a separate worktree, build the current compiler, then pass the unchanged distribution directory:

sh
node packages/twill/benchmarks/refinement.mjs \
  --baseline /absolute/path/to/baseline/packages/twill/dist \
  --output docs/benchmarks/refinement.json

Each worktree needs its frozen-lockfile dependencies. Keep other builds/tests idle during timing. The older reports below retain their original fixtures, environments and version boundaries; their absolute timings are not directly comparable to this run.

Synchronous loader registration in 0.3.1 ​

Version 0.3.0 uses asynchronous Node loader hooks. Version 0.3.1 prefers synchronous hooks when available, removing Twill's DEP0205 warning on Node 26 and the separate loader-thread handoff on that path. Older supported engines retain the compatibility adapter. Compilation, source maps and cache validation remain shared; valid hits and native delegation do not initialize the compiler. This changes interpreter startup, not generated application code or external-command execution.

The loader startup comparison builds the unchanged main revision before timing and compares actual old/new CLI launches. Each single-module and 25-import workload retains nine alternating fresh-process pairs for uncached, empty-cache and cache-hit execution, all raw observations, CPU/RSS observations and source/build identities. The Node 26 CI probe uploads loader-startup.json as the loader-startup artifact. Shared CI hosts introduce timing noise; these observations establish no general speedup or native startup parity. RSS is observed at script completion, not measured as a peak.

Maintainers can reproduce from a built checkout with installed frozen-lockfile dependencies and the baseline commit available locally:

sh
node packages/twill/benchmarks/loader-startup.mjs \
  5a258030ef3876bfaec3a858134e8535d019dede loader-startup.json

Keep other builds/tests idle while measuring. The script creates and removes its own temporary baseline worktree and compares both variants on the same Node version and CPU affinity.

Compiler measurements ​

The following synthetic run was recorded on 2026-10-05, Linux x64, Node 24.19.0, an AMD EPYC 9V74 shared execution host. Each stage has five warmups and 15 timed samples. Syntax transformation preserves types; the plugin pipeline also erases types and lowers JSX. Both include high-resolution source maps with embedded source. Values are medians in milliseconds.

Stage10 callbacks100 callbacks1,000 callbacks
Syntax → TypeScript2.19 ms15.00 ms146.44 ms
Syntax → implicit members2.03 ms15.50 ms206.07 ms
Syntax → JSX components2.05 ms10.89 ms124.55 ms
TypeScript plugin pipeline5.02 ms22.05 ms209.55 ms
Component plugin pipeline6.89 ms30.51 ms307.01 ms

Callback source sizes are 599 / 6,089 / 61,889 bytes. Implicit-member fixtures contain twice as many callbacks (20 / 200 / 2,000) and are 839 / 8,489 / 85,889 bytes. Component fixtures contain 10 / 100 / 1,000 nested views and are 679 / 6,889 / 69,889 bytes. These timings exclude process startup, filesystem discovery, project type checking, bundler optimization, rendering and editor UI. They are not whole-application build or runtime measurements. The compiler report includes p95 values, build identity and environment metadata.

Cleanup cost ​

Each cleanup workload invokes a function 10,000 times per batch. The single-direct case registers one cleanup; the dynamic loop registers 1 / 10 / 100 cleanups per invocation. Cleanup adds to observable state. The reference performs the same additions in native finally, using a direct statement or reverse loop without registration closures or a stack. Each implementation has a separate batch call site, result assertions, 50 warmup batches and 15 timed samples.

WorkloadRegistrations per invocationGenerated defer, median batchNative finally, median batchRatio
Single direct statement10.010 ms0.010 ms1.0×
Dynamic loop10.245 ms0.014 ms18.0×
Dynamic loop101.055 ms0.085 ms12.5×
Dynamic loop10019.745 ms0.828 ms23.8×

The single-direct output matches a minimal handwritten callback/finally implementation after ordinary host minification. V8 can optimize this small, warmed-up example; its near-equal timing does not mean every cleanup closure is free. Dynamic registration exposes allocation and dispatch overhead in a tight synchronous loop. These measurements do not establish an application slowdown ratio, real I/O cleanup latency, or results on other engines.

Guards and switch expressions ​

Destructured guards add a temporary and a nullish branch, followed by native destructuring. They add no wrapper object, callback or library. Direct-return switch expressions add a scoped native switch without a function. The standalone identifier-initializer path uses a result temporary and native labelled branches without a function. Other expression positions use one synchronous lexical arrow IIFE; this, arguments and scheduling retain native semantics. Selected object cases destructure the discriminator too, so a discriminator getter is read twice. Rest/default costs remain native destructuring costs.

The branching report measures 1,000,000 calls per sample, 15 samples after warmup, with each native/dialect case in a separate process on Node 24.19 / AMD EPYC 9V74. Isolated processes avoid shared call-site feedback favoring whichever function runs first.

WorkloadTwill medianNative medianMinified function bytes Twill / native
Destructured guard2.49 ms2.50 ms75 / 75
Direct-return value switch2.76 ms2.89 ms77 / 77
Switch in a local initializer2.75 ms2.72 ms95 / 90

The initializer comparison uses a natural native switch assigning a local. The standalone identifier-initializer optimization removes the IIFE and preserves the original declaration, TDZ and mutability. Larger expressions, for headers, multiple declarators, destructuring, direct eval, JS JSDoc context and TS suppression pragmas retain the established expression path. Timing differences are not a general speedup claim or evidence that remaining closures never allocate. Other engines, cold execution, larger branches and captured values need application measurements. Await/yield inside a switch requires a direct return, avoiding hidden promise conversion or additional async scheduling.

The application bundle report covers five supported paths. Guards, callbacks and a single React child match the native minified byte size. The direct object-pattern switch is 205 bytes versus 203 bytes: its explicit lexical block adds two braces. Tests enforce those exact output budgets and runtime parity. There is no Twill runtime imported into these application fixtures. Dynamic cleanup, general child collection and arbitrary expression switches have separate costs and are outside this parity claim.

Optional branch bindings ​

RFC 0018's if const emits a single initializer snapshot, a strict null/undefined test and a success-local const binding. Ordinary initializers add no function, runtime import, wrapper or scheduling. Object/array defaults, getters, iterators and rest retain their native costs. A nested match initializer retains the existing general-expression lowering and its synchronous IIFE cost.

On 2026-10-07, Node v24.19.0 on an INTEL(R) XEON(R) PLATINUM 8573C shared Linux host, each case ran seven pairs of isolated processes with alternating launch order. Each worker performs five warmups and 15 samples of 1,000,000 calls. Inputs cycle through null, undefined and present values including zero. The reported ratio is the median of the seven paired median-time ratios:

WorkloadTwill / natural handwritten JS
Identifier binding0.96×
Single-evaluation lookup call0.93×
Object destructuring1.03×
Array default and rest1.03×

All four medians pass the controlled-host 1.10× target. Individual trial ratios vary substantially (0.44×–1.26×); these observations support comparable performance in this run, not a stable speedup or a cross-engine/application guarantee. The complete report retains every timing, cold call, checksum, generated/minified source, source/build hash and implementation commit. Standalone minified functions add 11–21 bytes over these native baselines; the separately bundled object-binding application adds 10 bytes. Neither byte count is a runtime timing claim.

Reproduce after building with pnpm benchmark:if-bindings --output ../../docs/benchmarks/if-bindings.json --verify-performance. Run this separately from CPU-intensive validation to reduce host contention. Timing remains an acceptance measurement; CI checks semantics, output structure and byte budgets deterministically.

Mixed projects and editing ​

The project benchmark uses isolated processes, one-third native TypeScript and two-thirds Twill, plus a module importing every file and a member-callback document. Cold checks include TypeScript standard libraries; warm checks, edited-hover requests and partial-member completions use 15 samples. Values below come from the project report on the same host.

Source filesCold checkWarm check p50 / p95Edited hover p50 / p95Member completion p50 / p95Peak process RSS
102501 ms1.2 / 1.8 ms17.9 / 30.1 ms0.29 / 21.3 ms412 MiB
502726 ms6.0 / 12.5 ms39.4 / 69.7 ms0.27 / 23.8 ms485 MiB
10021020 ms10.3 / 21.2 ms71.0 / 100.6 ms0.38 / 29.3 ms598 MiB

The project stays alive while a 1,000-closure file is formatted. That cold, single-sample operation took 410–434 ms. Peak RSS therefore includes both the formatter and TypeScript; it is not incremental editor overhead. Measurements exclude VS Code rendering, the native TS-server bridge, dependency-heavy applications, HMR and application runtime.

Unchanged editor snapshots, transforms and mapping decoders are cached. The native TS-server bridge applies only changed overlays, retaining unrelated snapshots and script versions. The linter uses line indexes for source mapping rather than parsing additional ASTs. Edits invalidate affected files, while configuration changes rebuild affected projects. Typed ESLint includes program construction and freshness checks; syntactic lint offers lighter feedback. No editor responsiveness SLA follows from these synthetic results.

Application output and distribution budgets ​

The RFC 0018 branch binding uses a hygienic initializer snapshot and native success-scope binding. It introduces no runtime allocation, function, promise or helper import; native rest destructuring still allocates its own rest value. The checked object-binding application fixture allows at most 10 extra minified bytes for that snapshot compared with a handwritten branch over an already evaluated parameter. This budget is separate from runtime timing. benchmark:if-bindings records isolated native comparisons, all samples and generated/source/build checksums; --verify-performance checks the 1.10× controlled-host target.

Equivalent native and dialect application fixtures are built with real esbuild bundling and minification. An implicit-member filter/map pipeline emits 76 bytes in both forms; a guarded numeric pipeline emits 88 bytes in both forms; a React single-child component emits 121 bytes in both forms. The checks compare byte counts and executed behavior, and reject compiler/runtime dependencies in the application graph. Identifier mangling can choose different short names. React's normal JSX runtime is external in this comparison. These small fixtures do not cover every application, dynamic cleanup or general child collection.

The VSIX ships one pinned TypeScript engine shared on disk by its two editor hosts, standard-library declarations, the checker and the lightweight formatter. The engine still runs in each host process; sharing its distribution does not imply shared process memory. The standalone formatter loads TS/ESTree support rather than Node's automatic parser discovery.

Distributed builds enforce these compressed artifact size limits:

ArtifactMaximum compressed size
Compiler tarball650 KiB
Formatter tarball24 KiB
Linter tarball24 KiB
Highlight tarball24 KiB
Export tarball28 KiB
Optional runtime tarball8 KiB
Shell SDK tarball16 KiB
VSIX, including its engine3 MiB

Tarball budgets cover the package's own files, not installed npm dependencies. Development tools remain outside application bundles. These are distribution limits, not application bundle budgets or build-time guarantees.

React framework source study ​

The React source study compares the real React 19.3.0 client-core entry graph after identical Flow erasure. It adds an independently reproducible framework workload to the small synthetic fixtures above. The report includes production bytes, gzip size, interleaved build samples and isolated core-runtime samples. ReactDOM/reconciler are not rewritten; this is not a full rendering-throughput or typed framework-port benchmark.

Explicit enum patterns ​

RFC 0016's match expressions and explicit case descriptors are erased by native TS. Direct-return patterns and standalone identifier initializers use native switches and per-arm const destructuring without an IIFE. Other expression positions keep the existing synchronous IIFE. The preferred match spelling uses the same lowering; regression tests require emitted JS identical to the earlier explicit-marker spelling. Native rest bindings allocate/copy normally. The checked TS application bundle fixture with defaults/rest is 182 bytes versus 180 bytes for handwritten JS: two outer scope braces, with no matching runtime, factory access/call or additional result record. CI enforces that 2-byte budget and verifies runtime behavior and dependency absence.

On 2026-10-07, Node v24.19.0, Linux x64, INTEL(R) XEON(R) PLATINUM 8573C, three separate warmed processes per variant, pinned to CPU 0, ran 1,000,000 calls per sample, five warmups and 15 samples each. Launch order alternated, and the table aggregates all 45 measured samples. Both variants compiled the dialect once before sampling to balance compiler setup. Inputs cycle through idle and two loaded records; observable checksums agree. These are medians for one batch:

WorkloadGenerated patternNative baselineRatio
direct-named-payload6.40 ms6.21 ms1.03×
expression-named-payload6.74 ms6.64 ms1.02×
native-object-rest34.62 ms33.15 ms1.04×

The first prototype used an expression IIFE and measured 3.05× slower than native local assignment. That avoidable function is removed for standalone identifier initializers: the new measured path is comparable to native, rather than accepting the earlier slowdown. The checked application fixture adds 8 bytes and CI rejects an added arrow/IIFE. The direct and rest paths are also comparable in this run; none establishes a general speedup. Remaining expression-wrapper contexts need independent measurement/optimization. Rest costs reflect native allocation in both implementations; no application or cross-engine guarantee follows.

Synthetic typed files contain 10 / 100 / 1,000 functions sharing two variants. Transform timings include high-resolution maps; the native transform parses an unchanged TS file. Cold checks include creating a project and reading standard libraries; they are single observations, not sampled medians:

FunctionsPattern → TS medianUnchanged TS transform medianPattern cold checkNative cold check
108.44 ms5.55 ms1064.14 ms903.29 ms
10029.50 ms25.95 ms678.42 ms407.08 ms
1000357.09 ms327.84 ms2273.75 ms613.77 ms

Unchanged pattern diagnostics have cached medians of 0.02–0.07 ms. The descriptor rename guard indexes each file once and caches symbols by Program. Its first request on the 1,000-function fixture takes 397.29 ms, including mapping/symbol work; cached requests take 0.37 ms median. Edits invalidate the Program cache. These costs concern synthetic compiler/checker requests, not visible editor latency.

The report records inputs, p95, checksums, environment, base commit/tree, dirty-working-tree status and build/script digests. The source was an unreleased implementation checkout. Reproduce with pnpm build then pnpm benchmark:enum-patterns --output enum-patterns-results.json. Runtime tests use unchecked JS lowering; erased TS descriptors and native imports are additionally covered by checked bundle and package tests. Timing ratios are observations; correctness, absence of runtime dependencies and bytes are deterministic CI gates.

Optional runtime helpers ​

RFC 0032 adds opt-in external helpers; inline remains the default. Dynamic synchronous cleanup shares a small runDefers function. Single direct cleanup, explicit async and mixed cleanup retain identical output, including scheduling. The helper centralizes draining; registrations still allocate callbacks and a lazy array. It does not remove the allocation costs shown in the minimal-finally comparison above.

The runtime report compares generated inline/external output with handwritten native code having the same dynamic registrations and failure contract. Each sample executes 500,000 function calls. The recorded Linux run pins every worker to CPU 0. Three separate processes per variant, alternating launch order, contribute all 45 samples after 20 warmup batches. Each sample records wall and process CPU time; the gate compares wall medians. All workers perform the same compiler setup before timing; checksums and cleanup order agree. First-call and bundle-build timings are unsampled observations, not startup guarantees.

Registrations per callNative medianInline / nativeExternal / native
01.71 ms1.07×1.01×
121.93 ms0.99×0.99×
556.81 ms1.04×1.02×
25259.77 ms1.03×0.97×

The first review report is retained: its 100,000-call batches, five warmups and unpinned workers failed the same 1.10× target (1.28× inline and 1.17× external at one registration). Trial medians differed substantially, including within the native baseline. The revised run increases batch size/preheating and fixes CPU affinity; it changes no generated algorithm and keeps every trial/sample. Both inline and external pass the wall-median target in the revised run. Individual trials and p95 still vary; these medians do not establish a universal speed guarantee.

Separate synthetic modules are bundled as minified ES2022 ESM, including every byte of the actual helper. Gzip uses level 9:

Modules with dynamic cleanupInline bytes / gzipExternal bytes / gzip
1237 / 191256 / 195
102,289 / 2571,570 / 264
10023,007 / 82914,904 / 836

At 100 modules the external helper removes 35% of uncompressed output; gzip is approximately equal. A single module can grow. Split chunks and multiple installed versions can change sharing. CI enforces a 256-byte minified helper budget, one dependency-free helper in the application graph, no runtime import for inline output, and representative bundle/behavior budgets.

Reproduce after pnpm build with pnpm benchmark:runtime --output runtime-results.json --verify-performance. The optional flag rejects a median over 1.10× native for either mode and retains the full report before failing. The same flag is available for benchmark:enum-patterns. On Linux, prefix the command with taskset -c 0 (or another allowed CPU) to reproduce the recorded affinity; the report records it. This is a performance review target on a controlled host; investigate repeatable failures rather than accepting material regressions or treating noisy CI clocks as a portable gate. These synthetic results establish comparable performance for the measured paths, not a general speedup over optimized native code.

Evaluate your application ​

Measure build time, edited-file feedback and representative runtime paths before and after adopting a module. Use the same dependencies, hardware and production build settings. Inspect emitted code and bundle size, and exercise cleanup and error paths; warmed microbenchmarks can hide allocation costs that matter elsewhere.

The reports above include their inputs, sampling methods, environment and build identity. Instructions for reproducing repository benchmarks are in the contributor development guide. Correctness and output budgets are enforced; wall-clock thresholds are not enforced across different runners.

Earlier Node shell SDK measurements ​

The earlier shell implementation executed through native Node spawn / libuv, without command translation or a runtime compiler dependency. Inherited/discarded descriptors bypass capture. Explicit capture retains bounded chunks and concatenates/decodes once at settlement; the byte limit is not a total heap/RSS cap.

pnpm benchmark:shell --output ../../shell-results.json --verify-performance compares equivalent successful direct-child work with handwritten spawn: native/Node inherited output, dual binary capture and text stdin/capture. Nine paired samples alternate order, retain parent CPU and wall time separately, and include source/build hashes. The local gate requires a median wall ratio at most 1.10 and a paired bootstrap interval within tolerance; inconclusive samples do not pass. Separate reports cover parent memory observations at 1 MiB/8 MiB per stream, native/SDK/Twill cold startup and an execFile capture reference. Memory sampling is not a hard peak bound. No universal speedup, cancellation, concurrency or process-tree claim follows from these workloads.

The recorded source/build-identified samples include both an inconclusive whole-batch run and the accepted operation-interleaved run. The latter measured warm wall ratios 1.003–1.013 (all 95% upper bounds below 1.04), with comparable capture RSS observations. Dual capture adds about 10% parent CPU in this environment; child CPU is outside that metric. Native/SDK/Twill-source cold medians were 84.8/91.3/567.5 ms including one child. Native export avoids the source loader's compiler startup; warm SDK parity does not establish cold-source parity.

The early runner cache measurements retain 21 fresh-interpreter pairs and compiler/dependency validation. On this Linux/Node 24 workload, uncached/empty-cache/cached/native medians were 513.6/544.3/157.3/43.9 ms. The paired cache-hit ratio was 0.2938 (95% interval 0.2826–0.3046); empty-cache paired overhead was about 7%. These are source-startup observations, not native parity, external-command acceleration or Rust measurements. A valid hit skips compiler initialization; prebuilt JavaScript remains the faster first-launch path.

Rust subprocess experiment (historical) ​

Historical prototype, before 0.2.0. This section compares the experimental addon with the earlier Node SDK. Version 0.2.0 used the production Rust shell backend described below; its independent reactor addressed the prototype's worker-pool contention. Version 0.3.0 uses the Node SDK above. Keep these older measurements separate from production results and compiler startup.

The repository also contains an isolated Linux Rust/N-API experiment. It owns a direct child and nonblocking pipes, drains both output streams in one native loop and transfers captured buffers through N-API. It is outside published SDK files and cannot be selected through Subprocess.run; the measurement baseline used the earlier Node SDK. No Rust interpreter or compiler port is involved.

On Linux x64 / Node 24.19.0, eleven paired batches compare the prototype with the then-current Node SDK and handwritten Node spawn. All six operation orders rotate; every result is verified, and parent CPU includes native worker threads but excludes child work. Independent C producers expose launch/I/O costs; a Node producer includes its interpreter startup. These are observed paired ratios, not application-wide speed guarantees:

Successful workloadRust / SDK wall ratio95% paired bootstrap intervalRust / SDK parent CPU ratio
Short native executable, inherited output0.5810.563–0.6120.467
Native producer, dual 1 MiB capture0.5820.478–0.6080.645
Native producer, dual 8 MiB capture0.8520.815–0.9040.869
Native 1 MiB stdin/text capture0.6010.551–0.7220.677
Node producer, dual 1 MiB capture0.8980.879–0.9760.494

Short launches and native dual 1 MiB capture reduce paired wall time by about 42%; dual 8 MiB capture reduces it by about 15%. Node inherited-output launches have an inconclusive Rust/SDK interval (0.940–1.040). External commands do the same work; these gains belong to launch and capture coordination. The full report also retains the handwritten Node comparison, full-duplex input, every raw sample and source/build/toolchain identities.

Isolated capture RSS-increase medians were 4.13 MiB for SDK versus 2.31 MiB for Rust at 1 MiB per stream, and 33.21 versus 16.30 MiB at 8 MiB per stream. These 1 ms observations plus settlement are not hard peak bounds. Native allocation accounting differs from V8's external/arrayBuffers; use RSS to compare the process, and do not infer zero allocation/copying.

Two measured limits prevented adopting that prototype unchanged. Actual Twill runner startup had no demonstrated Rust improvement: cached SDK/Rust medians were 177.4/173.7 ms, with paired ratio 1.013 and interval 0.904–1.047; uncached medians were 514.4/525.8 ms. This addon leaves Node/compiler initialization intact. Also, each experimental native operation occupies a libuv worker: 32 parallel Node children with a 100 ms wait took observed medians of 473 ms for the earlier SDK and 1,185 ms for Rust with the default four-worker pool. Raising the pool to 32 measured 477/456 ms, but does not establish an independent scheduler or eliminate contention with filesystem/DNS work.

The addon is 495,808 bytes uncompressed, excluded from the SDK's existing 16 KiB archive gate. It snapshots input/environment and tests byte bounds, statuses, failures, deadlines and direct-child reaping on Node 20.19/24. It uses generic errors and immediate termination; graceful cancellation, bounded join, environment shutdown, containment, pipelines and Windows/macOS parity remain unimplemented. A production backend needs independent asynchronous scheduling and the full ownership/platform contract before adoption. See the experiment and reproduction instructions and RFC 0036.

Node shell SDK in 0.3.0 ​

Version 0.3.0 withdraws the Rust addon and experiment in favor of Node spawn/streams with zero production dependencies. It keeps the 16 KiB SDK archive gate and the complete seven-warm/two-concurrency comparison against equivalent handwritten Node. Historical Rust ratios below describe 0.2.0, not this replacement. Abrupt worker/process-exit cleanup and numeric unnamed-signal guarantees are intentionally retired; see scripting.

The measurement history retains every failed assessment, individual sample and source/build identity. The final inherited-state fast-path report at 502be6f, Linux x64 / Node 24.19.0, records:

WorkloadPaired SDK / handwritten Node wall medianUpper 95% bound
Native inherited launch0.9931.026
Empty Node child1.0161.039
Native dual 1 MiB capture1.1711.232
Native dual 8 MiB capture1.0501.095
Node dual 1 MiB capture1.0281.064
1 MiB stdin/text capture1.0281.062
Native full-duplex 1 MiB1.1131.157
32 concurrent Node children1.0001.009
128 concurrent Node children1.0091.025

The native 1 MiB capture and duplex workloads exceed the historical 1.10 target. The maintainer accepted these measured costs for 0.3.0 on 2026-10-09; the report still fails the optional strict comparison. This is a documented release tradeoff, with roughly 17%/11% median overhead in those two synthetic workloads, not a claim of universal native parity or a general speedup. Node interpreter launches and concurrency have separate, much smaller observed wall differences. Parent CPU excludes child CPU and is retained independently.

Default cwd/environment capture delegates to synchronous Node spawn, avoiding duplicate environment copies and unnecessary child chdir; explicit policies retain their handling. CPU-profile diagnostics investigated retained chunks and growing buffers; both candidates were withdrawn. Their exact snapshots and profiles remain in the measurement history.

Fresh handwritten Node/SDK medians are 52.4/55.6 ms, cached Twill baseline/SDK 166.7/177.0 ms, and uncached 503.6/515.0 ms. Parent CPU, memory, filesystem availability and cancellation observations remain separate in the raw reports. No universal speedup or native-source startup parity follows.

Rust shell backend (historical 0.2.0) ​

The @swiftuijs/twill-shell SDK in 0.2.0 uses @swiftuijs/twill-shell-native as its automatically installed prebuilt Rust engine and implements the complete direct-child SDK contract with one independent asynchronous reactor per Node environment. Native process creation runs synchronously on the calling Node thread, matching Node spawn. Unix readiness notifications and overlapped Windows pipes handle already-started children without a libuv worker per command. It preserves byte bounds, typed errors, cancellation, bounded join and environment cleanup. Byte input is copied at submission; captures and decoding still allocate. The prior optional-backend reports below retain the earlier Node SDK as a historical baseline; 0.2.0 provides one public Rust-backed SDK.

The complete-contract report measures the production implementation on 2026-10-08, Linux x64, Node 24.19.0 and Intel Xeon Platinum 8573C, with Rust 1.90.0. Eleven paired warm samples interleave all six handwritten Node / SDK / Rust orders between individual operations. Sequential work uses CPU 0; concurrency uses CPUs 0–3, matching the host's four-CPU quota. Each backend receives the same workload affinity. Output and termination status are checked outside timing. Parent CPU includes the Rust reactor and excludes child CPU.

Warm operationSDK medianRust medianPaired Rust / SDKPaired Rust / native (95% interval)
/usr/bin/true, inherited I/O2.99 ms1.95 ms0.648×0.645× (0.620–0.651)
Empty Node child38.01 ms37.77 ms0.963×0.969× (0.954–0.990)
Native dual capture, 1 MiB8.33 ms4.88 ms0.575×0.591× (0.552–0.617)
Native dual capture, 8 MiB30.59 ms22.89 ms0.737×0.731× (0.676–0.744)
Node dual capture, 1 MiB50.45 ms45.54 ms0.918×0.915× (0.886–0.935)
Native stdin/text echo, 1 MiB7.50 ms4.98 ms0.675×0.682× (0.650–0.702)
Native full-duplex I/O, 1 MiB7.95 ms5.05 ms0.629×0.634× (0.623–0.659)

Capture sizes are per stream. Wall medians and paired-ratio medians are different statistics; dividing the displayed medians does not reproduce the paired ratios. These native executable launch/capture workloads reduce wall time by about 26–43% against the SDK in this run. Parent CPU ratios are 0.478–0.801 across all seven workloads. The addon accelerates coordination, not the child program's own work.

Default-pool concurrency uses 48 pairs per workload, with each of six orders appearing eight times. Each child runs Node with a 100 ms timer. The earlier experimental 2.5× slowdown is removed without enlarging the shared worker pool:

Concurrent childrenSDK medianRust medianPaired Rust / native (95% interval)
32572 ms563 ms0.998× (0.974–1.040)
1281850 ms1853 ms1.003× (0.983–1.022)

All seven warm workloads and both default-pool concurrency workloads pass the unchanged acceptance target: paired median and upper 95% bootstrap bound at most 1.10× handwritten Node. This is a controlled-host result, not a cross-platform performance guarantee. Five real OS/CPU CI targets separately verify behavior and independently installed Node 20.19 consumers.

Isolated capture RSS-increase medians are SDK/Rust 3.88/2.43 MiB at 1 MiB per stream and 32.38/16.37 MiB at 8 MiB per stream. Sampling at 1 ms plus settlement cannot establish a hard peak bound; native memory is not fully represented by V8 external-memory accounting. With UV_THREADPOOL_SIZE=1 and 32 live children, unrelated filesystem reads still complete before releasing those children. Forced cancellation with a 20 ms grace period joins the directly owned child; raw latencies are in the report. These lifecycle observations use atomic PID markers and reject nonpositive identifiers before cleanup.

Fresh interpreter/import/one-command medians are handwritten Node 53.9 ms, SDK 56.3 ms and Rust 60.6 ms. Actual Twill runner medians are SDK/Rust 187.3/192.2 ms with cache hits and 543.9/560.9 ms with caching disabled. Their paired ratios are 1.029× and 1.010×; there is no demonstrated source-startup improvement. The compiler and Node interpreter remain on that path.

The measured Linux addon is 781,016 bytes. The separately verified five-target CI archive is 1,814,079 bytes compressed; each binary stays below 2 MiB and the archive below 6 MiB. The public SDK retains its independent 16 KiB budget. Binary hashes, source fingerprints, archive digest and license verification are retained in the package evidence.

The measurement history and reproduction instructions retain every failed review, the interrupted checkpoint and continuation source. The checkpoint already contained all warm, memory and concurrency observations; its continuation completed lifecycle and cold measurements on unchanged sources/builds. Review found a PID-marker race in the benchmark tool; atomic-marker lifecycle measurements were then repeated and recorded separately, preserving the original observations. Earlier foreign-thread cleanup crashes were fixed in the backend and are covered by repeated fresh-process, worker and actual Twill-runner tests. No sample was dropped to pass a performance gate. Process-tree containment, pipelines and unsupported prebuild targets remain outside this direct-child contract.

Expanded platform coverage ​

The released 0.2.0 eight-target matrix added Linux musl and Windows ARM64, glibc 2.28 builds and Rust-reactor owned-child polling when Linux pidfds are unavailable/denied. The historical measurements above used the earlier readiness implementation and identified five-target archive. The expanded-platform evidence identifies eight successful actual OS/CPU/libc jobs, each with real process contracts, 100% JavaScript adapter coverage and independent Node 20.19 archive consumers. The inspected complete archive is 2,891,605 bytes; every binary remains below 2 MiB and the archive below 6 MiB.

The new complete Linux/Node 24 report uses the same controlled-host method and unchanged performance gate. All seven warm and both default-pool concurrency workloads pass: 32/128-child Rust/native median ratios are 1.002/0.999, with upper 95% bounds 1.023/1.022. Warm native launch/capture wall ratios against the SDK are 0.588–0.730. These are readiness-path observations on the identified Linux host, not cross-platform guarantees.

The actual denied-pidfd diagnostic runs Node under a verified syscall filter returning ENOSYS. Twelve pairs retain all six operation orders and compare checked short launches and dual 1 MiB capture with handwritten Node. Short-launch Rust/native median ratio is 1.080 (95% interval 1.071–1.106); dual capture is 0.642 (0.624–0.681). Polling adds short-command wait latency; the short-launch interval does not establish the complete run's 1.10 acceptance bound. The separately retained readiness diagnostic and exact diagnostic source keep these observations distinct. Parent CPU includes the Rust reactor; child CPU is excluded.

That historical implementation inspected Node's complete process report on the first native load. Fresh SDK/Rust interpreter/import/one-command medians in that run were 63.5/80.7 ms; cached Twill source medians were 202.3/259.6 ms. Those measurements do not attribute the whole difference to ABI detection.

0.2.0 public SDK measurements ​

The Rust-only report measures the public SDK against handwritten Node on the same Linux x64 / Node 24.19 / four-CPU-quota host. Eleven warm pairs alternate both operation orders; both default-pool concurrency workloads retain 48 pairs. All seven warm and both concurrency gates pass unchanged, requiring both paired medians and upper 95% bounds at most 1.10.

Warm workloadRust / handwritten Node95% paired interval
Short native launch0.6310.610–0.633
Node interpreter launch0.9830.946–0.999
Native dual 1 MiB capture0.5610.523–0.578
Native dual 8 MiB capture0.6400.634–0.685
Node dual 1 MiB capture0.8980.850–1.033
Native 1 MiB stdin/text0.6540.630–0.703
Native 1 MiB duplex0.5970.560–0.612
32 concurrent Node children0.9960.960–1.011
128 concurrent Node children0.9970.981–1.010

In that released implementation, ordinary Linux startup reads the current Node ELF interpreter with bounded descriptor reads, retaining the conservative report fallback for unknown/static layouts. Fresh native/SDK medians are 62.9/70.0 ms. Cached Twill source medians are 207.3/223.8 ms; its paired ratio is 1.110 with interval 1.039–1.191. Uncached source medians are 689.8/635.4 ms, with an interval spanning parity. These observations do not establish cold-source parity, isolate the ELF optimization's contribution or demonstrate a general startup speedup. The historical denied-pidfd latency tradeoff above also remains separately scoped.

The report preserves memory, filesystem, cancellation and cold observations alongside every warm/concurrency sample and source/build hash. Cold warmup initially failed on a workspace-only import after the dependency direction changed. A retained completion script verifies every unchanged runtime/build identity before fixing the unexecuted fixture's import and measuring only the eleven cold pairs; no earlier sample is repeated or removed. The measurement history retains the incomplete checkpoints, failure logs, completion source and exact serialized report.

The final 0.2.0 shell recheck retains a complete run after the Mac exit-race and unnamed-signal fixes. All seven warm workloads and both default-pool gates pass without changing sample counts or limits. Native launch/capture/input ratios are 0.555–0.679, Node interpreter launch is 0.948, and 32/128-child concurrency medians are 0.975/0.992 (upper 95% bounds 0.998/0.997). This is Linux readiness-path evidence; the report retains separate cold, memory, cancellation and filesystem observations, and establishes no universal or external-command speedup.

Toolchain optimization ​

These optimizations ship in 0.4.1. The following diagnostics compare the pre-release source build at 18cc8e4 against published 0.4.0. Original measurements are retained unchanged; their byte counts and hashes do not describe rebuilt 0.4.1 release artifacts. Artifact identities and all package comparisons retain byte sizes and SHA-256 hashes. Both minimum VS Code 1.95.3 / TS 5.6.3 and stable VS Code 1.144.0 / TS 6.0.3 run the extracted VSIX, including cold/deferred formatter loading and the original coverage gates.

ArtifactPublished 0.4.0Source build
VSIX compressed2,796,981 bytes584,718 bytes
VSIX extracted14,591,130 bytes2,312,282 bytes
Compiler npm archive, retaining maps625,013 bytes502,260 bytes
Playground compiler worker, gzip340,876 bytes306,154 bytes

The earlier host-engine-only source build was 661,433 bytes. Parser deduplication, deferred formatting chunks and one retained editor license notice reduce that further to 584,718 bytes. The extension activation entry falls from 1,997,182 to 428,230 uncompressed bytes; formatting still works offline and loads its 1,426,622-byte chunk when first requested. Byte counts do not establish activation latency or RSS. Formatter, highlighting and runtime archives remain byte-identical. Shell runtime files and package metadata values are unchanged; key ordering changes the archive by one byte. Export's archive grows by twelve bytes while delaying its backend for help/invalid arguments.

Fresh-process Linux/Node 22.23.4 CLI diagnostics pin CPU 0, warm each pair once and retain eleven alternating paired samples per command. stdout, stderr and status match the reference on every invocation. The baseline's declared dependencies are linked from the same installed workspace dependency tree. Raw CLI observations and source/build identities retain every sample.

CLI workload0.4.0 medianSource median
Help504.8 ms30.2 ms
Compile help526.0 ms29.3 ms
Invalid option552.6 ms29.8 ms
Compile one small module to TS542.3 ms489.0 ms
Compile the same module to JS611.0 ms562.9 ms
Check the same module1,571.0 ms1,521.2 ms

These cold-command observations do not establish large-project checking, application or script-runtime speedups. Compiler algorithms, generated-language costs, the loader/cache and subprocess execution are unchanged.

The lint line-index diagnostic compiles the old/new source through the same Twill/TypeScript pipeline. It uses three paired warmups and eleven alternating paired samples, each constructing 32 indexes and checking observable coordinates. All allocations and spontaneous GC remain inside timing. Construction after/before paired median ratios are 0.136 without newlines, 0.271 for sparse LF, 0.904 for dense LF and 0.941 for mixed CRLF/CR/Unicode/LF. These measure the indexing step, not complete ESLint execution. Raw line-index observations and source/build identities preserve all results. Functional tests compare every UTF-16 offset against TypeScript coordinates and LF-only source-map coordinates.