Extension C-API v1

Overview of the current PYRS extension C-API v1 surface and guarantees.

PYRS exposes an extension C-API v1 slice for native extension bring-up. This is an active substrate, not full CPython C-API parity.

Version and Entry Contract

Field	Current contract
Header	`include/pyrs_capi.h`
ABI version	`PYRS_CAPI_ABI_VERSION = 1`
Init symbol	`pyrs_extension_init_v1(const PyrsApiV1* api, void* module_ctx)`
Handle model	Init-scoped object handles with explicit `incref/decref` operations.

Implemented Surface Categories

Category	Examples
Module globals and attrs	`module_set_*`, `module_get_object`, `module_set_attr`, `module_has_attr`
Object constructors and getters	`object_new_int`, `object_new_string`, `object_get_int`, `object_get_string`
Container and mapping helpers	`object_len`, `object_get_item`, `object_set_item`, dict/list helpers
Callable registration and invocation	`module_add_function`, `module_add_function_kw`, `object_call*`
Buffer and capsule interop	`object_get_buffer*`, `capsule_new`, `capsule_import`
Error and capability introspection	`error_set`, `error_get_message`, `api_has_capability`

Lifecycle and Scope Notes

Module-state lifecycle helpers are present (module_set_state, module_set_finalize).
Per-surface behavior is regression-tested in extension smoke fixtures.
Unsupported surfaces should fail explicitly instead of silent fallback.

Canonical Internal References

docs/EXTENSION_CAPI_V1.md
docs/EXTENSION_CAPABILITY_MATRIX.md
docs/EXTENSION_PACKAGING_CONTRACT.md
include/pyrs_capi.h