AGENTS.md@packages/native ยท diff
git:20261008.3d680c0 to git:20261106.b87924d
3 added, 6 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# Agent Guidelines for `packages/native`
## Purpose
- Rust native addon (napi-rs) loaded by the worker as `@langfuse/native`.
Exports telemetry, the startup probe, the prepared-event Native codec, and
Topics clustering. Topics runs in a Node child so its synchronous fit can be
killed at the deadline. See `README.md` for build and deployment layout.
## Maintenance Contract
- `index.js` and `index.d.ts` are generated by `napi build`. Never hand-edit
them; rebuild and commit the result whenever `src/lib.rs` exports change.
- Building the worker needs the pinned Rust toolchain: CI runners get it from
rustup auto-install on first `cargo` use; `worker/Dockerfile` installs the
- same version from the checksum-pinned standalone musl installer on Alpine.
- Bump `rust-toolchain.toml` together with that version and both per-arch sha256
+ same version from the checksum-pinned standalone installer on UBI9. Bump
+ `rust-toolchain.toml` together with that version and both per-arch sha256
values (`https://static.rust-lang.org/dist/rust-<version>-<triple>.tar.gz.sha256`).
The pin starts equal to `ai-gateway/rust-toolchain.toml` but the files are
deliberately separate.
- Native code reports through the `metrics` and `tracing` facades set up in
`src/telemetry.rs`; never return values for Node to record. Configuration
mirrors dd-trace and the winston logger (`DD_*`, `LANGFUSE_LOG_*`).
- The worker calls `initTelemetry()` once in `worker/src/initialize.ts` and
imports functions from `@langfuse/native` directly; keep call sites few.
- Keep finite Rust commands behind the package's `rust:*` scripts so pnpm's
shared `langfuse-rust` concurrency group also covers builds launched by Turbo.
- `PreparedEvent` snapshots finalized JS rows into owned Rust fields;
`encodeClickhouseEvents()` asynchronously encodes batches of those handles.
Keep column definitions in `src/native_schema.rs` and JS handles off worker threads.
## Verification
- `pnpm --filter @langfuse/native run lint` (rustfmt + clippy with
`-D warnings`).
- `pnpm --filter @langfuse/native run build`, then
`pnpm --filter worker run typecheck` and
`pnpm --filter worker run test nativeHello`. The test loads the compiled
addon; `pnpm turbo run test --filter=worker` builds it first, a direct
vitest run does not.
- - For Topics numerical changes, run `cargo test --features napi/dyn-symbols topics`
- here and `pnpm --filter worker run test features/topics` from the repository root.
- Compare grouping and final classifier assignments, not raw 2D coordinates,
- when changing the numerical backend.
+ - For Topics numerical changes, run `pnpm --filter @langfuse/native run test topics` and `pnpm --filter worker run test features/topics` from the repository root. Compare grouping and final classifier assignments, not raw 2D coordinates, when changing the numerical backend.
- When touching the build pipeline, build the worker image:
`docker build -f worker/Dockerfile .` and check `/api/health` on it.