Metadata-Version: 2.4
Name: coakka-v2-connector
Version: 3.2.1
Summary: CoAkka Runtime Python connector
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3.11
License-Expression: Apache-2.0 AND LicenseRef-CoAkka-Native-Artifact-1.2
License-File: LICENSE
License-File: NATIVE-LICENSE.md
License-File: PACKAGE-LICENSE.md
License-File: NOTICE
Description-Content-Type: text/markdown

# coakka-v2-connector

![CoAkka](https://raw.githubusercontent.com/phuong-tran/coakka-samples/main/docs/common/assets/brand/coakka-logo.png)

**The Python connector for CoAkka Runtime, a native-backed, polyglot
distributed runtime for application-owned work.** Keep business handlers in
Python and call work by target name across languages, processes and hosts.
The shared native core owns delivery and outcomes; the connector presents
those capabilities through familiar Python values and context managers.

## Version `3.2.1`

`3.2.1` is the first Python connector revision for Core generation `3.2`.
Each platform wheel includes Core 3.2, build
`f9e5a632d2d046a5b4e89d5ce0c9042aee5c7b45`, ABI 1, and its Python adapter.
Use GIL-enabled CPython 3.11 or later. The wheels have no Python runtime
dependencies. Applications migrating from 2.x must adopt the API introduced
in 3.0.0.

## Install

Create a virtual environment and install the matching wheel from PyPI.

```sh
python -m venv .venv
# macOS and Linux
. .venv/bin/activate
python -m pip install --only-binary=:all: coakka-v2-connector==3.2.1
```

On Windows, after creating the environment, run
`.venv\Scripts\python.exe -m pip install --only-binary=:all: coakka-v2-connector==3.2.1`.

## Quick Start

Save as `first_run.py` and run `python first_run.py` in the virtual
environment. It registers a local handler, prints `accepted-Ada Lovelace`,
and closes the host on exit.

```python
from coakka_v2_connector import ConnectorStartSpec, RuntimeHost, local_route


def accept_name(payload: bytes) -> bytes:
    return b"accepted-" + payload


target = "customers.accept"
start_spec = ConnectorStartSpec(
    system_name="customer-app",
    node_id="customer-app-1",
    routes=[local_route(target)],
)

with RuntimeHost.start(start_spec=start_spec) as runtime:
    runtime.register_payload_handler(target, accept_name)
    reply = runtime.ask_payload(
        source="customer-api",
        target=target,
        payload=b"Ada Lovelace",
        timeout_ms=2000,
    )
    print(reply.decode("utf-8"))
```

See [Python transport configuration](https://github.com/phuong-tran/coakka-publish/blob/main/docs/coakka-runtime/reference/python-configuration.md),
the [compatibility matrix](https://github.com/phuong-tran/coakka-publish/blob/main/docs/coakka-runtime/reference/compatibility-matrix.md),
and the [CoAkka documentation](https://github.com/phuong-tran/coakka-samples/blob/main/docs/README.md).

Current package shape:

- `RuntimeHost.start(...)` as the preferred single-process lifecycle entrypoint
- `ConnectorOrchestrator.start(...)` remains as the compatibility name for the
  same runtime host
- `PythonRuntimeClient` as the lower-level request/reply engine
- `submit_request_typed(...)`, `submit_request_json(...)`, `submit_request_raw(...)`
- `terminal_events(buffer_capacity=...)`
- typed payload identity helpers around `message_type`,
  `payload_schema_version`, and `payload_format`, including
  `PayloadIdentity.text(...)`
- `local_route(...)` for same-process targets so first-run samples do not spell
  host/port placeholders or endpoint flag numbers by hand
- control snapshot apply helpers
- monitor notification wait helpers
- Core-issued startup and delivery snapshots; omitted execution and
  connection intent is submitted as `AUTO`, with current effective connection
  mode `MULTIPLEXING`
- `ask_payload(...)` and `register_payload_handler(...)` for a bytes-first
  path whose framing, request reading, terminal matching and native buffer
  release are owned by Core
- one active runtime host per Python process
- capability discovery before selecting optional connection features
- startup-configured connection strategy and structured apply results

The bundled Core 3.2 does not provide public TCP TLS or mTLS. The security
APIs below apply to Core builds that report those capabilities.

Request/reply lane in Python now has two host API shapes over the same runtime contract:

- `ask_*`: submit and wait inline
- `submit_request_*` + `terminal_events(...)`: submit now, consume terminal outcome (`response` or `deadletter`) later through a stdlib queue-backed subscription

`terminal_events(...)` is a connector-owned API shape, not a separate backend mode. The current transport backend remains an implementation detail underneath.

## Before / After

CoAkka is easiest to understand from a fake backend HTTP handoff. The
browser/API edge can be real HTTP and should stay HTTP. The fake part is the
second private endpoint a team adds only so app-owned store work has something
URL-shaped to call:

```python
@app.post("/backend/customers")
def create_customer(command: CustomerDraft):
    return store.create(command)
```

The caller now owns URL config, HTTP parsing, status mapping, timeout mapping,
retry policy, logs, and test fixtures for a boundary that is not really a
public API:

```python
reply = requests.post(
    "http://customer-store/backend/customers",
    json=command,
    timeout=5,
)
reply.raise_for_status()
customer = reply.json()
```

Read the address change like this:

```text
Before fake backend HTTP:
  POST /api/customers -> requests.post("http://customer-store/backend/customers")

After CoAkka:
  POST /api/customers -> target "samples.customer.store" -> registered handler
```

After CoAkka, HTTP can stay at the real edge, and the private backend URL
becomes a runtime target owned by the process that handles it:

```python
from coakka_v2_connector import (
    ConnectorStartSpec,
    PayloadFormat,
    PayloadIdentity,
    RuntimeHost,
    local_route,
)

start_spec = ConnectorStartSpec(
    system_name="customer-store",
    node_id="customer-store-node-1",
    routes=[local_route("samples.customer.store", 19102)],
)

def handle_customer(request):
    return runtime.client.make_json_reply_from_request_identity(
        request=request,
        source="samples.customer.store",
        payload={"status": "accepted"},
    )

with RuntimeHost.start(start_spec=start_spec) as runtime:
    runtime.register_handler("samples.customer.store", handle_customer)

    response = runtime.ask_json(
        source="samples.customer.frontend",
        target="samples.customer.store",
        payload={"name": "Ada"},
        payload_identity=PayloadIdentity(
            "samples.customer.create.request.v1",
            1,
            PayloadFormat.JSON,
        ),
        timeout_ms=5000,
        operation="create_customer",
    )
```

The important change is not "HTTP is bad." Public HTTP and gRPC still belong at
real API edges. CoAkka removes the extra backend HTTP surface when the caller
and handler are application-owned capabilities that only need typed runtime
delivery, request/reply completion, and deadletter visibility.

`ConnectorOrchestrator` remains available for existing code. New Python code
should prefer `RuntimeHost` so the file reads as one embedded runtime owner,
not a remote connector setup.

Version 3.0.0 retains `separate_delivered_request_lane` as a compatibility
input, not a statement of actual delivery topology. Read the accepted topology
from `runtime_snapshot()` and `runtime_startup_config()`; native-engine Core
may require its separate owned request reader regardless of that input.
Descriptors are not evidence of the active engine.

In this release, `queue_capacity`, `enable_monitor` and `network` default to
`None`, preserving omission. Queue omission submits Core's zero selector and
uses its accepted capacity; Python does not substitute a capacity table.
Monitor omission leaves Core's default OFF, distinguishable from explicit
`False` in `defaultedGroups`. Monitor signals follow Core's accepted collection
permission. Network omission leaves Core's native EMBEDDED default with
`explicitPolicy=False`; explicit EMBEDDED remains distinguishable as explicit.
`runtime_network_config()` and the combined snapshot copy those Core facts.
Optional network ports retain presence, including an explicitly supplied zero;
Core alone decides whether that field applies or a reachable endpoint is valid.

`strict_no_drop=True` remains the builder's explicit safe intent for the frozen
base C ABI, whose required boolean has no absence state; it is not reported as
a discovered Core default. Always read effective values from Core snapshots.
Runtime info exposes `transportProvider`; runtime config exposes
`transportBindHost` and `transportBindPort`. These copy Core's public transport
facts, not a connector probe or a claim that an input bind preference was applied.
Historical pre-release inspection names are not retained as aliases.
Configuration models no longer expose a local `require_valid()` policy pass.
Core rejects invalid routes, generations, network or overload intent on
construction/apply, preserving its numeric status. Python retains only type,
ABI-width and NUL-safe C-string conversion checks. Payload-identity helpers
still enforce their declared typed application-value shape, not runtime policy.

Bytes-first handlers run synchronously on the sole Core request-reader turn
and must return promptly. Typed handlers use a bounded Python worker queue.
Each queued typed job keeps only its encoded frame, accepted one-way flag and
handler binding, not a second payload/target projection. Workers decode owning
Python message values. Application-retained messages/callback graphs use the
application's memory budget; queue slot limits are not a whole-heap byte cap.
Handler and asynchronous-terminal workers are started lazily, rather than
creating idle Python workers for a bytes-only host.

Handler registration owns Python callable references and exact UTF-8 target
keys, not native route admission. It requires a callable and a real boolean
for typed-reply intent; Core still validates routes and request admission.
Empty or NUL-bearing callback keys can be represented without claiming that
Core accepts a corresponding route. Duplicate registration is refused rather
than replacing a live callback. Once host close begins, both handler shapes
refuse new registration before publication. A registration racing close may
finish first, but cannot publish into the detached closed registry.

Successful close retires the reader/workers and native calls, detaches the
callback map under its publication lock, then releases its roots outside both
registry and close locks. Application finalizers can re-enter closed APIs;
registration still refuses and close is idempotent. Caller-held references,
cycles and application-finalizer completion remain application/GC concerns,
not a native resource or liveness fact. Handler-map count and retained callable
graph bytes are application-determined; whole-host pressure qualification is
still required before release.

`take_background_error()` on the client or host transfers the first unclaimed
Python worker exception, or returns `None`. It works after close and preserves
the original type, numeric fields, cause and traceback. This diagnostic is not
a Core delivery outcome. Close does not erase it: a traceback can retain
callback/request objects until the error is taken and released. The caller
owns the taken exception graph. One retained error is a count bound, not a byte
bound; later errors are not queued while that slot is occupied. Concurrent
takers have one winner. No callback or error finalizer runs under its lock.
Reader-side projection or value/dispatch-publication exceptions use this same
first-error slot and end that reader loop, without replaying work. A full
diagnostic slot keeps its earlier exception.

Candidate construction prepares language bookkeeping before creating Core and
guards its remaining queue/thread activation. If construction fails, no native
runtime/client/reader owner is published; a late-starting reader cannot enter
Core after rollback. The reader is retired before native destruction.
Native output guards cover the call, status projection and value copying, not
only the final copy. An unpublished runtime, reader, ask client/ticket, exported
host handles, frame, encoded/copied bytes or decoded-value lease is retired
through Core's corresponding cleanup API when Python raises after native
completion. Returned data never borrow released native storage. Null success
is a contract error, not an inferred allocation failure; native refusals retain
their numeric status. This is not a guarantee against process termination or
an interruption/failure inside cleanup itself.

Resource cleanup does not roll back accepted application work or consumed
terminal results. A lost ticket/frame/result is not silently retried. Closing
host handles does not reset Core's one-shot export; retiring the sole reader
does not make its Core source reusable. Failed construction retires that
runtime; a new construction uses a new Core owner. No connector OS probing or
native-state reconstruction is involved.
Call `close()` from an external application owner after handlers return, not
from a connector reader/handler worker. Worker-origin close raises `RuntimeError`
before changing lifecycle state, so request handling can finish and the
external owner can still close. There is no hidden deferred-close thread.

`RuntimeHost.start(...)` guards its newly started client until facade creation
and process-slot publication succeed. A facade construction error closes that
unpublished client before propagating. One factory slot covers the base host
and facade subclasses; construction is non-reentrant. Register handlers only
on the returned host. Close keeps the slot occupied while the client drains,
without holding the factory lock across worker/native retirement. A refused
close leaves the facade open and slot occupied, so an external owner can retry;
only successful close releases the process slot.

Connection startup is reported through Core's accepted
`runtime_startup_config()["connection"]` receipt and live
`tcp_connection_config()`, not a synthesized apply result. Version 3.0.0 removes
the former `startup_connection_result()` compatibility projection: explicit
settings do not prove a `changed` outcome. `RuntimeTcpConnectionStrategySpec()`
contains no overrides and submits Core AUTO by omission; it never forces
PER_EXCHANGE. Current Core selects MULTIPLEXING. Startup receipts remain
historical accepted facts after close, not a liveness check. Live inspection
errors propagate without a fallback to the retained receipt. Actual security
and explicit connection apply results still come directly from Core.

Candidate terminal/deadletter observers use language-owned bounded buffers
with an out-of-band closed state, not a queued sentinel. Closing a subscription
unregisters it without stopping Core; closing the host wakes all its observer
waiters and refuses new subscriptions. All previously accepted items remain
available in FIFO order, then `get()` returns `None` without waiting. Full
buffers still drop newly observed items and increment observer drop counters;
this does not change Core delivery/admission. Subscription wrapper construction
finishes before registration, so allocation failure leaves no hidden observer.
Close needs no list snapshot or extra queue slot. Per-observer capacity is an
item-count bound, not a total Python heap or global subscriber/byte budget;
the latter remains part of private package-pressure qualification.
Observer wait timeouts must be finite and non-negative, or `None` for an
explicit indefinite wait; shutdown still wakes that indefinite wait.

Runtime FFI inputs use the actual storage value of `bytes`, `str` and `int`,
including their subclasses, rather than overridden length/conversion hooks.
Ordinary builtins keep identity; subclass snapshots may require a boundary
copy. Native lengths and integer widths are derived only afterward. This is
memory-safe value projection, not an alternative encoder or Core policy check.

The bytes-first path reuses immutable source/target encodings in two private
64-entry tables. Only keys through 128 UTF-8 bytes are eligible; this is a
cache bound, not a Core input limit. Larger values and full-table misses are
encoded uncached and submitted unchanged. Cached encoded values total at most
25,088 bytes, plus bounded text keys and Python table/entry overhead. Calling
threads hold only weak shortcuts, not extra retained keys or payloads; their
metadata count follows application-owned calling threads. Successful host
close clears both tables after native calls drain. Returned immutable bytes
remain owned by their caller through the synchronous native borrow.

Lazy handler and asynchronous-terminal groups admit work only after their
starts succeed. A partial or late start is retired before the error propagates;
it does not stop the valid host or publish a failed handler. Registration can
be retried. Group-local cancellation preserves normal host stop and accepted
ticket cleanup; each language role is bounded to one or two workers. This is
Python scheduling ownership, not a claim about native thread count or affinity.

Candidate native calls which require a successful status raise
`CoreCallError`, a `RuntimeError` subtype, on refusal. Its integer `status`
and string `operation` preserve Core's result, including unknown status values;
applications must not classify failures by parsing exception text. The ask
constructor uses Core's status/out-owner contract once, without retry or a
fallback to the old pointer-only constructor. Only success transfers an owner.
A success result with no owner is a separate contract error, not an invented
resource-exhaustion status. Dedicated structured policy errors remain as
documented in [Python transport API](https://github.com/phuong-tran/coakka-publish/blob/main/docs/coakka-runtime/reference/python-configuration.md).

The rich request/reply API introduced in 3.0.0 uses frozen Python `Message` values,
not generated schema objects. Headers are copied into a read-only mapping;
use `dataclasses.replace(message, correlation_id="another-id")` to derive a
value. Builders such as `make_json_request(...)` return this same type. There
are no generated-message serialization methods: Core alone
encodes and decodes through its public message-value contract. Numeric kind,
business status, format, hint and schema version preserve their values,
including unknown codes and status zero; text is UTF-8 with length-bearing NUL
support and payload is opaque `bytes`.

`Deadletter` preserves an absent `original_envelope` as `None`, endpoint-attempt
facts and Core-issued `DeliveryFailure` dimensions when present. Unknown causes
remain unknown with bounded raw metadata retained; the connector does not
interpret detail text. Every returned value owns Python copies after Core's
lease is released. This boundary keeps Core's 64 MiB frame, 1 MiB packed
metadata and depth-16 decode limits; these are not a cap on all transient
Python/parser memory. Unknown wire fields are not retained and property order
is unspecified. Invalid representation is refused without an alternate codec.
Python checks only host-type/ABI-width conversion here; Core owns semantic
admission and routing. This is a new 3.0.0 API, not a compatibility shim
for historical wheel schema classes. Exact installed wheel qualification and
whole-host pressure remain promotion controls.

Candidate route updates also use Core's control-value encoder. It preserves
generation, sequence, source diagnostics and an omitted versus explicit
overload policy; semantic route/policy admission remains Core's apply step,
not the encoder. Format values keep full ABI-width intent rather than silently
narrowing endpoint ports or unknown enums. Encoded bytes are copied and Core's
temporary owner is released even if the subsequent apply refuses. Core bounds
the table/text charge and encoded update to 1 MiB each. The source candidate
runs rich request/reply using only Python's standard library; schema tooling
is test-only. Historical wheel metadata/embedded payloads are not promoted by
this source result; candidate wheels have their own frozen artifact receipts.

For route updates, `overload_policy=None` means absent: Core resolves its
configured boot-time policy, not the last active policy or a replay of the
Python startup input. A `RuntimeOverloadPolicy(...)` is complete explicit
intent, including an all-zero policy. Startup submits its initial intent once.
Read `runtime_config()`'s `configured*OverloadMode` /
`configuredRemoteOutboundReplyReserveSlots` and corresponding `effective*`
fields for Core's boot/active facts. Stale/invalid updates retain the active
route/policy pair and original numeric refusal. Control source/sequence are
diagnostics, not sequencing or authorization policy: only an omitted source
chooses the connector's system-name label; explicit empty/NUL text and zero
sequence remain unchanged through encoding.

Runtime observation calls copy Core-issued values before their native borrow
ends. Configuration read and string copy are serialized together, since a
later configuration getter can retire the preceding borrowed view. Host close
also waits for admitted observation calls. `runtime_snapshot()` identities
come from the same Core configuration copy included in that aggregate, not
the original input objects. The aggregate combines independent samples, not
one atomic whole-runtime transaction. Inspection refusal propagates its Core
status; no input value or guessed default is substituted.

Hot-path reading note:

- false-sharing is not the first-order hot-path concern for this Python layer
  in the same way it is for the native C++ connector
- the current Python connector cost center is more likely to sit in:
  - native value projection around Core-owned calls
  - Core value conversion and Python object mapping
  - queue/subscription churn around `terminal_events(...)`
  - thread and event handoff topology
- only revisit cacheline-style hardening here if this layer later moves toward
  packed native-side state, off-heap rings, or a flatter shared-memory layout

Runtime library resolution order:

1. explicit `runtime_lib_path` passed to `RuntimeHost.start(...)`
2. `$COAKKA_RUNTIME_LIB`, when present
3. the exact image named by the installed wheel's bounded package receipt

Empty/invalid explicit intent is an error, never absence. Installed Core and
host-adapter images load directly from the package directory after their
size/hash/identity checks;
there is no process temp cache, executable extraction, cwd/system-library
discovery or fallback after package damage. Receipt traversal/duplicates,
missing/linked/changed image and stale identity fail before native loading.
These checks protect the packaged byte pairing, not publisher authentication
or hostile filesystem replacement between inspection and loading. Signing is
a separate release gate. Zip import is unsupported. The installer chooses a
wheel's OS/ISA tag; the connector does not probe OS capabilities to select one.
Core reports actual runtime capabilities/defaults after load. Old platform /
versioned-name normalization helpers are removed from the 3.0.0 API.

Each platform wheel pairs the bundled Core with its Python adapter.
Current matching-host qualification covers these GIL-enabled CPython builds:

| Distribution target | Wheel tag | Qualified host and interpreter |
| --- | --- | --- |
| macOS ARM64 | `cp311-abi3-macosx_13_0_arm64` | macOS ARM64, CPython 3.11.15 |
| Linux ARM64 | `cp311-abi3-manylinux_2_35_aarch64` | Raspberry Pi 5, CPython 3.11.15 and 3.13.5 |
| Linux x86-64 | `cp311-abi3-manylinux_2_36_x86_64` | WSL2 Linux on physical Windows, CPython 3.11.18 |
| Windows ARM64 | `cp311-abi3-win_arm64` | Windows 11 ARM64 VM, CPython 3.11.9 and 3.12.10 ARM64 |
| Windows x86-64 | `cp311-abi3-win_amd64` | Physical Windows, CPython 3.11.9 x64 |

A platform-specific execution result does not imply execution on another
packaged target or on the minimum OS encoded by its tag. The ABI tag is an
installer compatibility contract, not execution evidence for every interpreter
version. PyPy and free-threaded Python are outside this qualification. Use
[common troubleshooting](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/operations/troubleshooting.md)
for OS/CPU selection, loader dependencies, digests, Gatekeeper, Authenticode,
and the explicitly documented absence of publisher signing.

## File Lane

In this release, File and Stream snapshot terminal flags come
from Core's terminal transition timestamp, not the numeric ordering of states.
File `PAUSED` is retryable and nonterminal; cancel can make it terminal. Success
also requires a recognized completed/ended state and an `OK` result. Core may
allow forgetting an inactive paused transfer separately: that permission does
not make `PAUSED` terminal. Do not wait for a paused transfer to complete without
choosing resume, cancel, or another Core-supported action.

`FileLane.open(...)` is a context-managed independent native bulk-transfer
lane. Its waits are blocking and `close()` stops the lane before draining
active calls. See the shared [file-lane contract](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/guides/runtime-file-transfer.md).

In this release, File/Stream `open(...)` and `open_owned(...)` prepare
Python bookkeeping before creating a native owner. A Python exception after
actual native create, failed handle publication or start stops that
unpublished owner before destruction, then propagates the
original failure. Native create refusals retain their numeric status; a
successful create without an owner is a separate contract error, not an
inferred allocation failure. This does not change Core configuration or lane
admission policy. Replacement-wheel qualification remains a separate gate.

Stream callback references are prepared before Core admission. A returned Core
refusal restores the previous callback; an outcome lost to a Python exception
retains both references until successful forget or lane destruction. Retrying
that unresolved session registration is refused locally until explicit
cancel/forget or close; this is not an inferred native session state.
Registration and forget serialize callback-reference handoff, without holding
that lock during callbacks or native stop. Session IDs use the same builtin
UTF-8 identity as the native spec; embedded NUL is rejected rather than aliasing
another C-string identity.

Python's callback-reference slots are bounded to the actual capacity read once
from Core, not an input/default table. A slot can retain two callbacks when an
admission outcome is unknown. Core's automatic record pruning is not a receipt
permitting Python to release a borrowed callback. Explicitly cancel/wait and
forget terminal sessions before admitting more distinct sessions. If references
fill the Python allocation bound, admission raises `MemoryError` before calling
Core; it does not fabricate a Core queue-full status or silently forget work.
Successful forget or lane destruction releases references. If Core already
pruned a record and forget refuses, references remain conservatively until
lane close. The bound is on Python FFI roots, not the size of application object
graphs those callbacks reference. Native session policy and decisions stay in
Core; this exception exists because Python owns its GC/FFI references.

If copying a newly issued grant fails, the connector requests Core cancellation
and forget. It releases the callback only after successful forget. An active
publisher may not yet be forgettable: the original Python publication exception
then includes Core's actual cleanup refusal as its cause, and the callback stays
rooted for explicit cleanup or close. No wait/retry timeout is added.
Call Stream `close()` from an external application owner, never from a native
callback or a reentrant admitted API call. Such close attempts raise
`RuntimeError` before changing state or invoking native stop. A native stop
refusal preserves the owner and callback references for an external retry;
only successful stop, admitted-call drain and destroy retire them.

File/Stream startup configuration submits intent directly to Core. The private
candidate removes `FileLaneConfig.require_valid()`,
`StreamLaneConfig.require_valid()` and `LaneOwnerConfig.require_valid()` rather
than retaining a second policy validator. Flags, worker limits, capacity
clamping, frame/window and pressure policy, security modes and owner identity
rules are decided by native create. Representable invalid intent raises the
lane's error with Core's numeric status and create operation; it is not changed
to a local validation error. Zero selectors remain zero for Core to resolve,
and capacity inspection reports Core's actual accepted capacity.

Startup FFI projection checks only integer type and ABI width, actual builtin
string storage, UTF-8/C-string representation and absence of embedded NUL.
Numeric fields require integers, not booleans or floating-point values.
Subclass conversion/comparison/truthiness hooks do not change submitted values.
Security's omitted pointer stays omitted; explicit empty optional text projects
to native null, while actual nonempty text is retained even for false-truthy
string subclasses. Core decides how that material applies to the selected
security mode. Config text and security storage remain owned through the
synchronous create call. Per-session/transfer values and reconstructed grants
are not covered by this startup-only qualification.

File transfer, digest and control-call inputs now use the same actual-value
projection. Numeric widths are checked before native conversion; Core decides
whether a representable port, size, identity, path or digest is acceptable.
The fixed 32-byte digest is copied from actual bytes storage, not an overridden
length or conversion hook. File paths pass through Python's path-value protocol
and filesystem encoding after builtin normalization; this performs no Python
stat/open/hash operation on the transfer file. Core owns those I/O operations.
Embedded NUL is rejected rather than truncating the native path/identity.

File `close()` refuses a reentrant admitted-call close before state changes.
A native stop refusal preserves the handle and wakes concurrent closers for an
external retry; no destroy is issued until stop succeeds and admitted calls
drain. Pointer-wrapper allocation failure does not mark a call or close gate.

File grant-copy errors deliberately differ from Stream compensation. File
prepare can re-adopt existing/resumable receive state; success does not prove
this call created a new record. If Python cannot copy the accepted grant, the
original error propagates and Core's bounded record remains available for
explicit inspect/retry with the same transfer ID, or cancel/wait/forget.
The connector does not automatically cancel a record it cannot prove is new.
This call is not an all-or-nothing transaction across Core admission and Python
allocation. Native stop/destroy still retires the lane; storage/resume behavior
remains Core-owned.

Stream session/control values likewise use actual builtin strings and exact
integer widths before native admission. Core owns session/token/format/frame /
window/endpoint policy and reports its own refusals; Python only checks
representation, callable type and the returned frame's actual borrowed-buffer
capacity. Source results must be `StreamSourceFrame` or `StreamSourceSignal`;
consumer results must be `StreamConsumerDecision` or `None` (continue).
Plain integers, booleans or arbitrary equality hooks do not stand in for those
signal/decision types in the new candidate.

Frame scalar values are copied once, normalized and width-checked before any
C-field assignment. Callback roots retain the application callable, not the
whole spec/authorization. The passed source/consumer view is released when the
application callback returns, including on exception. This retires that exact
view only: derived aliases cannot be revoked, and applications must not retain
any borrowed view. Copy bytes inside the callback if later ownership is needed.
Core still owns framing, credit, scheduling and final source/consumer outcomes.

The root bound is a slot-count bound, not a byte bound on arbitrary malformed
request text. Normally accepted session identities obey Core's limits. If a
call's status is lost to a Python exception, its original key can remain pinned
even if Core actually refused it. A missing record is not a release receipt;
unresolved roots stay count-bounded until successful forget or lane close.
Whole-host input/heap-byte pressure remains private qualification work.

`LaneOwnerEndpoint`, `FileReceiveGrant` and `StreamPublishGrant` are frozen
value containers, not local semantic validators. Version 3.0.0 does not
impose a second token alphabet or duplicate Core's owner/format/frame policy in
their constructors. Core-issued opaque UTF-8 tokens, including spaces and
Unicode, survive issuance and reconstruction unchanged. ABI type/width/NUL
and fixed-digest safety still apply when intent crosses into Native; Core owns
semantic admission and its original refusal status.

A reconstructed value is not proof of authentication, issuer provenance,
native admission or current owner liveness. The application must obtain grants
through its authenticated control plane and preserve the exact owner endpoint;
it must not treat successful dataclass construction as trust validation. Issued
values copy Core facts at issuance, not a promise that the owner remains alive.

Owner-grant discovery uses the shared Core information view. A failed native
inspection raises `CoreCallError` with its numeric status and
`runtime_get_info` operation; it is not reclassified as unavailable. Only a
successful inspection reporting the feature absent raises
`LaneOwnerGrantUnavailableError`. An advertised feature with missing required
symbols is an artifact-contract `RuntimeError`, not a guessed unsupported state.

## Stream Lane

Use the [streaming contract](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/guides/runtime-streaming.md).
For replicas, use `FileLane.open_owned(...).prepare_receive_grant(...)` or
`StreamLane.open_owned(...).prepare_publish_grant(...)`, then reconstruct the
dataclass from the authenticated response and call `to_send_spec(...)` or
`to_subscribe_spec(...)`. See the
[owner-grant ONE/ALL sample](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/reference/runtime-lane-owner-grants.md).

## AI-Assisted Integration

Before generating application code, use the selected connector README together
with the public [AI-assisted integration guide](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/guides/ai-assisted-integration.md).
It requires an exact package coordinate, platform evidence, the runnable
language sample, and the feature-specific lifecycle contract. Do not translate
API identifiers from another language by analogy.


## License

**Free for application use, including commercial and production use.**

Connector source, generated bindings, type declarations, examples, and package
documentation use the [Apache License, Version 2.0](https://github.com/phuong-tran/coakka-samples/blob/main/LICENSE).
Bundled Native Core files use the [CoAkka Native Artifact License 1.2](https://github.com/phuong-tran/coakka-samples/blob/main/NATIVE-LICENSE.md).
Those native terms permit ordinary application and SaaS use but require a
separate agreement to sell or offer CoAkka itself as managed runtime or
infrastructure.

See [CoAkka Package Licensing](https://github.com/phuong-tran/coakka-samples/blob/main/docs/common/package-licensing.md)
for the file-scope map. The package also carries offline `LICENSE`,
`NATIVE-LICENSE.md`, `PACKAGE-LICENSE.md`, and `NOTICE` copies.
