Retention and lifetime

An interface can be valid while a provider is answering a request and invalid as soon as that call returns. Copying its pointers does not tell the provider to keep anything available. TTX makes a longer access duration explicit, so inspecting a temporary result does not require every caller to retain it.

Observing a result within its scope

Import interprets represented input and supplies an Abstract during a synchronous callback. Create similarly supplies a newly created Abstract. The consumer can navigate, bind capabilities or copy values while that callback is active. The provider remains free to use temporary storage for the graph result.

A plain Abstract carries no hidden release obligation. Its supplying call or owner defines how long its context, operation table and referenced metadata remain available. Binding another API from that Abstract does not silently acquire a new lifetime.

Asking to keep the result

If the consumer needs the graph after its current access ends, it can negotiate Retain. A successful call returns Retained and transfers one release obligation to the consumer. The provider may keep the original state available or supply different state that preserves the Abstract's graph location and policies.

For example, the Godot extension needs a constructor after it has finished inspecting an exported class. It retains the graph that supplies the constructor and method bindings. When it creates an instance, it also retains the resulting instance before the creation callback ends.

Each successful retain is a separate acquisition, even if two results use the same context. Copies of one Retained record and interfaces bound through its Abstract share that result's release obligation. The consumer releases each acquired result once after every dependent interface has finished using it.

An operation that transfers a release obligation returns Retained or a stronger contract exposing that obligation. Hiding it behind a plain Abstract would leave the consumer unable to determine when cleanup is required.

Keeping implementation code loaded

Retaining provider state and retaining its executable code are related obligations. A copied function pointer becomes unusable if its library unloads, including the function required to release an object. The Godot host keeps provider libraries loaded through every retained use. Individual objects can end earlier without removing code another result still needs.

This arrangement leaves allocation with each provider. A C counter, a script object and a device resource can expose the same lifetime contracts while using different storage. The consumer follows the release function published with each retained result rather than importing the provider's allocator.

Data has a separate boundary

Retaining an Abstract keeps its interface available; it does not by itself expose or copy a payload. Data transfer separately establishes the represented bytes that cross a boundary. A domain specific capability can add shared device storage or another access policy when a complete value copy is not the right operation.

The consumer finishes those data operations before releasing the Retained result that keeps their endpoints available. A failed operation does not authorize it to reach around the provider and inspect private storage.

The public Retain, Retained, Create and Import contracts specify these scopes and release obligations.