Summary
Create one canonical bindings-facing safety contract for Python, C, Go, and future language bindings.
This is an ecosystem compatibility issue. If ordvec is going to be a primitive embedded by larger systems, it should be a good neighbor by making ownership, lifetimes, panic boundaries, thread-safety, and input mutation rules explicit in one place.
Current gap
Concurrency and input-isolation topics are already being tracked in #113 and PR #114, and the C ABI has its own local contracts. The missing piece is a single normative document that all bindings can reference.
Proposed scope
Add docs/bindings-safety.md covering:
- who owns input and output buffers
- which APIs borrow vs copy inputs
- whether language runtimes/GILs may be released during calls
- index handle thread-safety and mutation exclusivity rules
- whether callers may mutate input arrays while calls are active
- how panics/errors cross each binding boundary
- how returned memory is freed in C/Go-style bindings
- how path-based load/write APIs should be sandboxed by host applications
Acceptance criteria
- Python, C ABI, and Go docs link to the same safety contract.
- Every exported FFI function has ownership/lifetime language or points to the canonical section.
- Panic boundary behavior is documented and covered by tests where practical.
- Concurrency and input mutation caveats are explicit.
- The document states what safety responsibilities remain with the host system.
Non-goals
- No new locking scheme by default.
- No database runtime policy.
- No automatic sandboxing or path policy beyond documented hooks/responsibilities.
Summary
Create one canonical bindings-facing safety contract for Python, C, Go, and future language bindings.
This is an ecosystem compatibility issue. If ordvec is going to be a primitive embedded by larger systems, it should be a good neighbor by making ownership, lifetimes, panic boundaries, thread-safety, and input mutation rules explicit in one place.
Current gap
Concurrency and input-isolation topics are already being tracked in #113 and PR #114, and the C ABI has its own local contracts. The missing piece is a single normative document that all bindings can reference.
Proposed scope
Add
docs/bindings-safety.mdcovering:Acceptance criteria
Non-goals