fix(codegen): construct private-field core types via Default-seeded builder (#160)

* fix(codegen): construct private-field core types via Default-seeded builder

Core structs with private (`pub(crate)`) fields cannot be built with struct-literal
syntax from a foreign crate — neither by naming the private field (E0451) nor by
patching it with `..Default::default()`. The generated binding->core `From` impls for
such types failed to compile against cores that moved internal fields behind
`pub(crate)` (e.g. extraction/OCR result types whose `internal_document` fields became
private).

Record a `has_private_fields` flag on struct IR during extraction, and centralize the
construction strategy in a shared helper (`conversions::construction`): seed the core
type's `Default` — built inside the defining crate, so it fills the private fields —
and assign only the public fields onto it. When the core type has private fields but
no `Default`, emit a `compile_error!` guiding the author to derive it. The helper is
used by the shared pyo3/napi/wasm/extendr/rustler/magnus generator and the Dart
mirror-crate generator, so every backend that builds core structs stays in lockstep.

Also repair two pyo3 trait-bridge regressions surfaced by the same core migration:

- Marshal owned (by-value) native-struct callback params into the host's native object
  via `From<core::T>`, as borrowed params already were. A trait method taking a serde
  struct by value (e.g. a URI-based extraction-input envelope) passed the raw `core::T`
  across the Python boundary, which has no `IntoPyObject` and failed to compile.

- When a core `register_*` free function shares its name with a trait bridge's
  `register_fn`, emit only the bridge's duck-typed registration. The function loop also
  emitted the auto-wrapped core version, which collided (E0428) and no longer
  type-checks against a registry that takes `Arc<dyn Trait>`.

Adds extractor and conversion-strategy unit tests; existing snapshots are unchanged
since no neutral fixture has private fields.

* fix(php): construct private-field core types and marshal owned bridge params

Extends the private-field construction fix to PHP's ext-php-rs paths, the last
backend still failing against the migrated core:

- The enum-tainted `From<Binding>` emitter (`gen_enum_tainted_from_binding_to_core`)
  collected its conversions into a struct literal, which cannot build a core type with
  private fields. It now collects `(field, expr)` pairs and delegates to the shared
  `conversions::construction` helper — the same `Default`-seeded builder / `compile_error!`
  strategy the other backends use — for private-field types, keeping the struct literal for
  fully-public types.

- Owned (by-value) native-struct callback params were dereferenced as if borrowed
  (`{Class}::from((*input).clone())`), which does not type-check on an owned `core::T`
  (`E0614`). Owned params now construct from the value directly.

- The native-object return fast-path emitted `<Binding as FromZval>::from_zval(&val)`, but a
  PHP `#[php_class]` binding struct implements `FromZvalMut` (for `&mut T`), not `FromZval`
  (for `T`). The bridge now keeps the JSON/string return path for every type — the
  well-defined path for PHP — rather than a native fast-path that cannot compile.

All seven generated binding crates (py/node/wasm/dart/ffi/swift/php) now compile against
xberg 1.0.0-rc.1.

* perf(trait-bridge): move owned native-struct params instead of cloning

The bridge marshalling cloned the owned core value when handing it to the host
(`T::from(owned.clone())`). The param — e.g. a by-value `ExtractInput` envelope carrying
document bytes — is consumed exactly once, so it is moved in instead. Borrowed params still
clone out of the `&`, which is unavoidable. Applies to the pyo3 (sync + async) and PHP
bridge generators.

* fix(pyo3): serialize dict/list JSON config fields in api.py converters

PyO3 cannot expose a settable serde_json::Value field (unlike NAPI's json_as_value), so
JSON config fields are stored as String in the binding while the public dataclass and .pyi
stub type them as dict[str, Any]. The generated api.py converter forwarded the dict straight
to _rust, raising 'TypeError: dict is not str' at runtime. Serialize a dict/list via
json.dumps in the converter; pass str/None through unchanged.

* fix(pyo3): enlarge async-runtime worker stack to prevent deep-future SIGBUS

pyo3-async-runtimes' default multi-thread runtime gives worker threads a small (~2 MB)
stack. A deep consumer future — e.g. a multi-stage PDF/OCR pipeline — overflows it and the
process aborts with SIGBUS (EXC_BAD_ACCESS, KERN_PROTECTION_FAILURE on the worker stack
guard page). The generated #[pymodule] init now installs a tokio runtime with a 16 MB
thread_stack_size via pyo3_async_runtimes::tokio::init before the first future_into_py.

Reproduced and verified fixed against a real consumer: an image-only PDF + tesseract OCR
aborted with exit 138 before, runs to completion after.

* fix(napi): enlarge streaming WORKER_POOL worker stack to prevent deep-future SIGBUS

Mirrors the pyo3 worker-stack fix for node: the generated streaming WORKER_POOL tokio
runtime used the default (~2 MB) worker stack, which a deep consumer future (e.g. an OCR
pipeline) overflows, aborting the process with SIGBUS. Build it with a 16 MB thread_stack_size.

Author: tobocop2

CHANGELOG.md

@@ -28,6 +28,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **napi**: give the generated streaming `WORKER_POOL` tokio runtime a 16 MB worker stack, so a
+  deep consumer future does not overflow the default (~2 MB) worker stack and abort with `SIGBUS`.
+- **pyo3**: provision an enlarged worker-thread stack on the generated module's async runtime.
+  pyo3-async-runtimes' default multi-thread runtime gives workers a small (~2 MB) stack, which a
+  deep consumer future (e.g. a multi-stage OCR pipeline) overflows — aborting the whole process
+  with `SIGBUS`. The `#[pymodule]` init now installs a `tokio` runtime with a 16 MB
+  `thread_stack_size` before the first `future_into_py`.
+- **pyo3**: serialize `dict`/`list` values for JSON (`serde_json::Value`) config fields in the
+  generated `api.py` converters. PyO3 cannot expose a settable `serde_json::Value` field, so the
+  binding stores such fields as `str`, while the public dataclass and `.pyi` stub type them as
+  `dict[str, Any]`. The converter forwarded the dict straight through, so the documented dict form
+  raised `TypeError: 'dict' object is not an instance of 'str'` at runtime; it now `json.dumps`es a
+  dict/list (passing `str`/`None` through unchanged).
+- **codegen**: generate compiling binding→core conversions for core structs that have private
+  (`pub(crate)`) fields. Such a struct cannot be built with struct-literal syntax from a foreign
+  crate — neither by naming the private field nor by patching it with `..Default::default()` — so
+  the conversion now seeds the core type's `Default` (which fills the private fields inside the
+  defining crate) and assigns only the public fields onto it. The strategy is centralized in a
+  shared helper used by the pyo3/napi/wasm/extendr/rustler/magnus generator, the Dart mirror crate
+  generator, and the PHP enum-tainted conversion path; when the core type has private fields but no
+  `Default`, a `compile_error!` guides the author to derive `Default`. A new `has_private_fields`
+  flag on struct IR records the condition during extraction.
+- **php**: marshal owned (by-value) native-struct callback parameters by value rather than
+  dereferencing them as a borrow (`(*input)` does not type-check on an owned `core::T`), and stop
+  emitting the native-object return fast-path — a PHP `#[php_class]` binding struct implements
+  `FromZvalMut` (for `&mut T`) but not `FromZval` (for `T`), so the bridge keeps the JSON return
+  path that is well-defined for PHP.
+- **pyo3**: marshal owned (by-value) native-struct callback parameters into the host's native
+  binding object via `From<core::T>`, the same way borrowed ones already were. A trait method that
+  takes a serde struct by value (e.g. an extraction-input envelope) previously passed the raw
+  `core::T` across the Python boundary, which has no `IntoPyObject` and failed to compile.
+- **pyo3**: when a core `register_*` free function shares its name with a trait bridge's
+  `register_fn`, emit only the bridge's duck-typed registration. The function loop no longer also
+  emits the auto-wrapped core version, which collided (`E0428`) with the bridge definition and no
+  longer type-checks against a registry that takes `Arc<dyn Trait>`.
 - **pyo3**: the generated Python package now type-checks clean under `mypy`. Data-enum config fields
   are annotated against their public class (so `EmbeddingConfig(model=EmbeddingModelType.plugin(...))`
   is accepted) instead of a flattened union alias that shadowed the class; constructors accept the

src/backends/csharp/gen_bindings/types/tests.rs

@@ -49,6 +49,7 @@ fn record_type(fields: Vec<FieldDef>) -> TypeDef {
         binding_exclusion_reason: None,
         is_variant_wrapper: false,
         has_lifetime_params: false,
+        has_private_fields: false,
         version: Default::default(),
     }
 }

src/backends/csharp/gen_visitor.rs

@@ -662,6 +662,7 @@ mod tests {
             binding_exclusion_reason: None,
             is_variant_wrapper: false,
             has_lifetime_params: false,
+            has_private_fields: false,
             version: Default::default(),
         }
     }

src/backends/csharp/trait_bridge/tests.rs

@@ -23,6 +23,7 @@ fn make_trait_def(name: &str) -> TypeDef {
         binding_exclusion_reason: None,
         is_variant_wrapper: false,
         has_lifetime_params: false,
+        has_private_fields: false,
         version: Default::default(),
     }
 }

src/backends/dart/gen_bindings/service_api/tests.rs

@@ -342,6 +342,7 @@ fn test_skip_sanitized_finalize() {
         binding_exclusion_reason: None,
         is_variant_wrapper: false,
         has_lifetime_params: false,
+        has_private_fields: false,
         version: Default::default(),
     };
 

src/backends/dart/gen_bindings/types.rs

@@ -276,6 +276,7 @@ mod tests {
             binding_exclusion_reason: None,
             is_variant_wrapper: false,
             has_lifetime_params: false,
+            has_private_fields: false,
             version: Default::default(),
         }
     }

src/backends/dart/gen_rust_crate/mirror_conversions.rs

@@ -465,6 +465,40 @@ pub(super) fn emit_from_mirror_to_core_struct(out: &mut String, ty: &TypeDef, so
         ty.rust_path.replace('-', "_")
     };
 
+    // Core types with private (non-`pub`) fields cannot be built with struct-literal syntax
+    // from the mirror crate. Seed the core `Default` (which fills the private fields) and
+    // assign the public fields onto it — via the shared construction strategy used by every
+    // backend. Excluded / lossily-sanitized fields are left at their default on the base.
+    if ty.has_private_fields {
+        let mut assignments = Vec::new();
+        for field in &ty.fields {
+            if field.binding_excluded {
+                continue;
+            }
+            let safe_sanitized_string = matches!(field.ty, TypeRef::String) && field.core_wrapper == CoreWrapper::Cow;
+            if field.sanitized && !safe_sanitized_string {
+                continue;
+            }
+            assignments.push(crate::codegen::conversions::construction::FieldAssign {
+                core_field: field.name.clone(),
+                expr: field_from_expr_to_core(field, source_crate_name),
+            });
+        }
+        out.push_str(&crate::codegen::conversions::construction::gen_private_field_from_impl(
+            &crate::codegen::conversions::construction::PrivateFieldImpl {
+                core_path: &core_ty,
+                binding_name: name,
+                param: "v",
+                has_default: ty.has_default,
+                assignments: &assignments,
+                allow_attrs: &[
+                    "clippy::field_reassign_with_default, clippy::let_and_return, clippy::useless_conversion",
+                ],
+            },
+        ));
+        return;
+    }
+
     // The generated literal ends with `..Default::default()` whenever some core
     // fields are intentionally omitted from the explicit field list AND the core
     // type derives Default (the spread itself requires Default — otherwise E0277).

src/backends/dart/gen_rust_crate/trait_bridge/tests.rs

@@ -25,6 +25,7 @@ fn empty_type_def(name: &str, is_trait: bool) -> TypeDef {
         binding_exclusion_reason: None,
         is_variant_wrapper: false,
         has_lifetime_params: false,
+        has_private_fields: false,
         version: Default::default(),
     }
 }

src/backends/extendr/gen_bindings/tests.rs

@@ -75,6 +75,7 @@ fn make_api_surface() -> ApiSurface {
             is_variant_wrapper: false,
 
             has_lifetime_params: false,
+            has_private_fields: false,
             version: Default::default(),
         }],
         functions: vec![FunctionDef {

src/backends/extendr/gen_bindings/tests/trait_bridge.rs

@@ -162,6 +162,7 @@ fn regression_namespace_exports_functions_types_enums() {
         is_variant_wrapper: false,
 
         has_lifetime_params: false,
+        has_private_fields: false,
         version: Default::default(),
     });
     // Add a flat data enum (has variant with data, single field)
@@ -300,6 +301,7 @@ clear_fn = "clear_greeters"
         binding_exclusion_reason: None,
         is_variant_wrapper: false,
         has_lifetime_params: false,
+        has_private_fields: false,
         version: Default::default(),
     };
     let doc_ty = TypeDef {
@@ -389,6 +391,7 @@ fn r_field_long_descriptions_are_truncated_to_fit_120_char_lines() {
             is_variant_wrapper: false,
 
             has_lifetime_params: false,
+            has_private_fields: false,
             version: Default::default(),
         }],
         functions: vec![],