@W-23692110: Harden multi-engine lifecycle and streaming

[mlischetti]

Summary

This draft layers the first completed PR #157 review-22 remediations onto w-23692110-multi-engine-design. It does not target master.

Completed through Task 5:

• add Java LIVE -> CLOSING -> DESTROYED engine lifecycle records and operation leases;
• make destroy_engine close admission and drain admitted operations;
• contain all seven GraalVM C entrypoints with explicit ABI exception sentinels;
• validate required entrypoint arguments without changing normal script-failure envelopes;
• remove the unused, unsafe ScriptRuntime.get(long) lookup;
• add raw-ABI subprocess coverage for process survival and resolver-context draining;
• reject same-thread Python lifecycle and execution reentrancy from native callbacks;
• bind Python operations and lazy streams to immutable {handle, generation} tokens;
• preserve handle-reuse safety and atomic cleanup/admission behavior;
• wake all queued operation waiters when serialized ownership is released.

Intentional Contracts

• destroy_engine may block until all previously admitted operations finish.
• Resolver and callback context storage must remain valid until destroy_engine returns.
• Same-thread DataWeave lifecycle or execution from a Python native callback raises DataWeaveError before lock acquisition or native attachment.
• Stale Python streams fail with a stale-generation error and never run against a replacement engine, even if its numeric handle is reused.
• Exported C names, argument order, callback semantics, and JSON wire fields remain unchanged.

Verification

• JAVA_HOME=<GraalVM 24> GRAALVM_HOME=<GraalVM 24> ./gradlew native-lib:test -PskipNodeTests=true -PskipPythonTests=true
  • Passed; GraalVM Community Java 24 native compilation and hosted Java tests completed successfully.
• python3 -m pytest -m unit -q
  • 168 passed, 75 deselected.
• DATAWEAVE_NATIVE_LIB=../build/native/nativeCompile/dwlib.dylib python3 -m pytest tests/integration/test_lifecycle.py tests/integration/test_module_resolver.py tests/integration/test_streaming.py -q
  • 28 passed.
• Focused generation admission tests
  • 4 passed.
• Focused stale stream/transform tests
  • 4 passed.
• git diff --check origin/w-23692110-multi-engine-design...HEAD
  • Passed.

The Python unit suite currently has a pre-existing approximately 30-second process-exit delay after reporting success. It was isolated to an older streaming cleanup test with a non-daemon consumer and reproduces before these changes.

Remaining Draft Work

• Node same-thread callback reentrancy guard.
• Node generation-bound lazy streams.
• TypeScript streaming operation controller and consumer credits.
• Native Node output backpressure and cancellation.
• Detach-poison failure injection and fail-closed admission.
• Final documentation, complete cross-language verification, and whole-branch review.

Relationship To PR #157

This is a focused follow-up branch for the eight findings from PR #157 review 22. The PR remains draft until the remaining Node, documentation, and final verification tasks are complete.