tai/taicpp/docs/embed.md

Embedding detz: research notes

Options compared:

1. Dynamic .so plugin (dlopen): flexible versioning, but host must ship/resolve the .so at runtime; symbol drift risk; packaging burden.
2. Subprocess/IPC (spawn detz binary): simplest isolation, but per-call latency + serialization cost; no in-process context hook.
3. Static archive link (chosen): build/libdetz.a + C ABI header src/glue/detz_embed.h (detz_set_context, detz_context, detz_version) plus C++ hook detz::embed::apply_context(). Single artifact, no runtime deps beyond system libs, version pinned at build time. make static additionally yields fully static build/detz-static (verified file: statically linked, ldd: not a dynamic executable) using vendored third_party/{curl,sqlite,jitterentropy} archives. Re-verified 2026-10-27 at 1.44.3: make static exits 0, the binary is 29 MB, file says statically linked, --version prints tai 1.44.3, and the link shows only the standard glibc static warnings (dlopen, getaddrinfo, gethostbyname, getpwuid).
4. Header-only: rejected — codebase too large, would explode host build times.

Why this API: minimal C surface (stable ABI, callable from C/Rust/Python-ctypes) with a thin C++ apply_context() injection point wired into GlueApp::one_shot, so hosts prepend context without touching agent internals. Proven: third-party TU links against libdetz.a and apply_context("ping") → [ctx] STATIC-PROOF\nping, version 1.44.3.