Metadata-Version: 2.5
Name: struct-sdk-native
Version: 0.1.12
Summary: Native capture runtime for the Struct observability SDK
Project-URL: Homepage, https://struct.ai
Project-URL: Documentation, https://struct.ai/docs
Project-URL: Issues, https://struct.ai/support
Author-email: Struct <support@struct.ai>
License-Expression: Apache-2.0
License-File: native/LICENSE
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# struct-sdk-native

Native capture runtime for the [Struct](https://struct.ai) observability SDK. `struct-sdk`
installs it automatically; you do not need to install or import it yourself.

Customer dynamic capture is not integrated yet. The package contains an internal function-boundary
hook primitive, native boundary-plan lowering, an ordinary-function dispatch/lifecycle engine,
and the compiler Struct's server uses to check
instrumentation definitions. `struct-sdk` does not load these during initialization:

```python
from struct_sdk_native import capability_report

capability_report().available  # False in this release
```

The internal lifecycle disarms inherited hooks after fork and requires explicit
`initialize(fresh_consumer)` in each worker. It supplies synchronous `suppress_capture()` scopes
and `shutdown(deadline)` using an absolute `time.monotonic()` deadline. The native outcome counts
describe consumer handoff, not export acknowledgement. Initialization establishes the process-owned
cleanup worker; shutdown and cleanup retries never start threads on the deadline-bound caller.
Retain the lifecycle and output adapter while cleanup is pending: active spans keep terminal hooks
until their original function returns and restores context, even after the delivery deadline.
Public `struct.init()` integration and
output/export lifecycle orchestration remain separate; no signal or exit handler is installed.

CPython 3.12 on Linux glibc (x86_64, ARM64, glibc 2.28 or newer) and macOS arm64 installs a
compiled wheel. Every other platform, including Python 3.13 and musl, installs a pure Python
wheel that reports the capability as unavailable. Neither case needs a Rust compiler, and no
source distribution is published.

The server's publication path uses `struct_sdk_native.sil.prepare_definition(bytes)` to revalidate
immutable stored artifacts outside database locks, then a fresh `configuration_index()` to check
every enabled observation's prepared versions together. Preparation preserves existing identities;
the index retains only target/metric signatures. Both call the shared Rust compiler with the GIL
released and report typed refusals. The customer SDK never imports this compiler surface.
