Add engine-reuse ergonomics: post-construction lazy globals and a snapshot scope

[lahma]

Two additions to Engine.AdvancedOperations, both answering friction found while adopting Jint in real hosts. They are independent; one commit each.

engine.Advanced.AddLazyGlobal(name, factory, flags)

Options.AddLazyGlobal defers building a global's value until script reads the name, but it is options-time only. Squidex (Squidex/squidex#1326) computes its globals from per-request data, which it only knows after new Engine(...), so it cannot use the registration at all. The workaround reachable from the public surface — FastSetProperty with a CustomJsValue descriptor of the host's own — is declined by the global-identifier inline cache, which never caches a CustomJsValue descriptor. Lazy per-request globals were a choice between eager construction and a permanently uncacheable read.

This is the options-time body invoked on a live engine: the same LazyPropertyDescriptor, which clears its CustomJsValue flag the moment it materializes and so rejoins the caches. Because it belongs to one engine rather than to a shared Options, its factory may capture engine-affine state — the case the options-time API deliberately cannot express.

engine.Advanced.AddLazyGlobal("user", _ => JsValue.FromObject(engine, request.User));
engine.Advanced.AddLazyGlobal("db", e => new ObjectWrapper(e, scope.ServiceProvider.GetRequiredService<IDb>()));

Neither is built for a script that never mentions the name, and in / hasOwnProperty / Object.keys(globalThis) still see both without building anything.

The one thing a post-construction install must get right

At construction time no inline cache exists yet, so an install that skipped invalidation would still be correct. On a live engine the handler trees may already hold a resolved binding for that very name, and a warmed identifier site keeps the previous descriptor by reference, revalidating it against GlobalObject._propertiesVersion alone. SetProperty bumps that counter on every path it can take — shared-layout slot replacement, hybrid side-dictionary add, plain dictionary store, deopt fallback — which is why the install goes through it rather than writing _properties directly. It correctly leaves _lexicalMutations and _envBindingInjectionEpoch alone: a global property is not a lexical binding and injects nothing into an existing environment, and bumping either would be invalidating caches for a change that did not happen.

That is not theoretical. A deliberately naive first implementation that stored straight into _properties failed three of the tests below: a warmed eager global and a warmed built-in both kept serving their old value forever, and the version-bump assertion failed on the first storage path it reached.

Snapshot interplay, stated as it falls out

Pinned rather than papered over, and documented on the method:

• a global installed after a capture is gone after the restore;
• one installed before a capture whose factory had not run at capture time is returned to that unmaterialized state, so it may run again on the next read.

The second follows from the IFieldBackedLazyDescriptor contract — restore rewrites _flags/_value, which re-arms the lazy. It is the desirable behaviour rather than an artifact: it is what lets a pooled engine keep the laziness across evaluations. A factory whose result must survive a restore has to be installed after it.

engine.Advanced.WithRestoredGlobals(snapshot, action)

CaptureGlobalSnapshot / RestoreGlobalSnapshot document the shape every reusing host ends up writing: lock, evaluate, restore in a finally. KurrentDB (kurrent-io/KurrentDB#5690) reported that recipe as correct but easy to get wrong, and the part that gets lost is the finally — invisible until a script throws, at which point the globals that evaluation declared are handed to the next caller. That is the exact failure the snapshot API exists to prevent.

lock (_gate)
{
    engine.Advanced.WithRestoredGlobals(_clean, () => result = engine.Evaluate(script).ToObject());
}

It is try { action(); } finally { RestoreGlobalSnapshot(snapshot); } and nothing else. Both arguments are null-checked; everything after that is left to RestoreGlobalSnapshot's own guards rather than duplicated, so a foreign snapshot or an outstanding asynchronous evaluation fails exactly as documented — after the action has run, since this adds a finally and does not pre-validate on the restore's behalf. A test pins that ordering so it is a stated property rather than an accident.

The doc deliberately does not oversell it: identical non-guarantees to RestoreGlobalSnapshot, linked rather than restated. It is still a configuration-reuse primitive and not an isolation boundary — a finally, not a sandbox.

Tests

Red-test-first throughout. Integrator-facing tests live in Jint.Tests.PublicInterface, the project without InternalsVisibleTo, so they prove the surface is genuinely reachable by a third party.

• Jint.Tests.PublicInterface/LazyGlobalRegistrationTests.cs (+11): a site that already failed to resolve the name, a warmed eager global and a warmed built-in each observe the new binding (identifier and member reads, on a shared Prepared<Script> so the second evaluation reaches the node the first warmed); the factory runs lazily and at most once; existence and enumeration do not materialize; flags honoured; a factory capturing engine-affine state; a null factory result becoming undefined rather than re-running; both snapshot directions; null arguments.
• Jint.Tests.PublicInterface/GlobalSnapshotTests.cs (+6): restore observed after normal completion, after a CLR throw from the action, and after a JavaScriptException from the script; restore runs exactly once and the engine stays usable; null arguments; the guard-ordering pin.
• Jint.Tests/Runtime/LazyGlobalInstallationTests.cs (new): the internals the public surface cannot see — which descriptor is stored and that it is stored unmaterialized, the version bump on all four storage paths, the two lexical counters asserted unchanged, and the IFieldBackedLazyDescriptor marker that makes the restore able to revert it.

Docs: the public-contract table in AGENTS.md gains both APIs plus a gotcha stating the invalidation invariant for any future post-construction global installer, and README.md's embedding section covers both.

Gate

dotnet build -c Release clean (TreatWarningsAsErrors), Jint.Tests 4592 net10.0 / 4512 net472, Jint.Tests.PublicInterface 1189 × 2 frameworks, Jint.Tests.Test262 99441 passed / 0 failed. All green.