Skip to content

docs: bindings-facing safety and ownership contract #123

@Fieldnote-Echo

Description

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation & integration guidesenhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions