coakka-http-runtime-python 1.1.2__cp311-abi3-win_amd64.whl

coakka_http/runtime.py

@@ -0,0 +1,555 @@
+'Low-level, lease-safe Python access to the host-inlined HTTP runtime.'
+from __future__ import annotations
+import ctypes
+import threading
+from collections.abc import Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass,fields
+from itertools import islice
+from typing import Iterator,Self,TypeAlias,TypeVar,cast
+from.import _native as native
+from.import _projection as managed_projection
+from.values import Activity,ApiAdditionalProperties,ApiExample,ApiMediaType,ApiParameter,ApiParameterLocation,ApiRequestBody,ApiResponse,ApiResponseHeader,ApiSchema,ApiSchemaDefinition,ApiSchemaKind,ApiSchemaProperty,ApiSecurityRequirement,ApiSecurityUse,BodyDelivery,Capability,Compression,CompressionMode,ControlCode,DrainOutcome,DrainState,Event,EventKind,ExchangeId,ExecutionInfo,ExecutionMode,ExecutionReason,ExecutionSelection,Failure,FileResponse,Header,Headers,Health,IoBackend,IoBackendFallbackReason,Limits,MonitorApplyOutcome,MonitorApplyReason,MonitorCategory,MonitorConfig,MonitorEvent,MonitorEventKind,MonitorEventPage,MonitorFailureCount,MonitorLatencyBucket,MonitorPolicy,MonitorSnapshot,NotificationProfile,OutboundTerminal,OutboundReason,OutboundPhase,OutboundRetry,OutboundCertainty,OutboundId,OutboundRequest,PathParameter,QueryParameter,Request,RequestRetirement,RequestRetirementCode,RequestRetirementState,Response,Route,RouteApiMetadata,RouteIdentity,RoutePublication,RoutePublicationOutcome,RouteRebind,RouteRebindOutcome,RouteSnapshot,RouteState,RuntimeConfig,RuntimeInfo,RuntimeInspection,ServicePlan,SseEvent,TlsCredentials,TlsReloadMode,TlsReloadOutcome,TlsReloadReason,TlsReloadRequest,TransportSecurity,WebSocketEvent,WebSocketEventKind,WebSocketId,_MAX_HEADER_COUNT,_EMPTY_HEADERS
+NativeError=native.NativeError
+_MAX_ITEMS=1<<20
+_MAX_WAIT_MS=60000
+_FAILED_INDEX_NONE=(1<<32)-1
+_REQUEST_EVENT_KIND=int(EventKind.REQUEST)
+_ServiceRequestEvent:TypeAlias=tuple[Request,int,int]
+_MAX_METADATA_COLLECTION_ITEMS=16384
+_MAX_METADATA_SCHEMA_DEPTH=128
+_MAX_METADATA_PROJECTION_BYTES=16<<20
+_MAX_METADATA_TEXT_BYTES=64<<10
+_MetadataValue=TypeVar('_MetadataValue')
+_NativeStructure=TypeVar('_NativeStructure',bound=ctypes.Structure)
+_ProjectedValues:TypeAlias=tuple[object,...]
+_ProjectedRequest:TypeAlias=tuple[int,int,int,int,int,int,str,str,str,str,tuple[str,...]|None,bytes,int,int,int,int,tuple[str,...]|None,tuple[object,...]|None,tuple[str,...]|None,bool]
+_ProjectedEvent:TypeAlias=tuple[int,int,int,int,int,int,bytes|None,tuple[str,...]|None]
+_ProjectedSuccess:TypeAlias=_ProjectedRequest|_ProjectedEvent
+def _unsigned(value:int,bits:int,name:str)->int:
+	if isinstance(value,bool)or not isinstance(value,int):raise TypeError(f"{name} must be an integer")
+	if value<0 or value>=1<<bits:raise ValueError(f"{name} is outside the unsigned {bits}-bit range")
+	return value
+def _timeout(value:int)->int:
+	value=_unsigned(value,64,'timeout_ms')
+	if value!=0 and value!=(1<<64)-1 and value>_MAX_WAIT_MS:raise ValueError('timeout_ms exceeds the 60-second connector bound')
+	return value
+def _init(value:ctypes.Structure,function_name:str)->None:getattr(native.LIBRARY.library,function_name)(ctypes.byref(value))
+def _native_exchange(value:ExchangeId)->native.Exchange:
+	if not isinstance(value,ExchangeId):raise TypeError('exchange must be an ExchangeId')
+	return native.Exchange(_unsigned(value.slot,64,'exchange.slot'),_unsigned(value.generation,64,'exchange.generation'))
+def _native_websocket(value:WebSocketId)->native.WebSocket:
+	if not isinstance(value,WebSocketId):raise TypeError('session must be a WebSocketId')
+	return native.WebSocket(_unsigned(value.slot,64,'session.slot'),_unsigned(value.generation,64,'session.generation'))
+def _native_outbound(value:OutboundId)->native.OutboundCall:
+	if not isinstance(value,OutboundId):raise TypeError('call must be an OutboundId')
+	return native.OutboundCall(_unsigned(value.slot,64,'call.slot'),_unsigned(value.generation,64,'call.generation'))
+class _PreparedHeaders:
+	'Header-owned immutable descriptors and encoded bytes, with no Core state.';__slots__='arena','pointer','count','cacheable'
+	def __init__(self,value:Headers)->None:
+		'Bound iteration before encoding; publish only the complete view.';entries=tuple(islice(value,_MAX_HEADER_COUNT+1))
+		if len(entries)>_MAX_HEADER_COUNT:raise ValueError('header count exceeds the Python projection bound')
+		if any(not isinstance(item,Header)for item in entries):raise TypeError('headers must contain Header values')
+		self.arena=native.Arena();projected=[native.Header(self.arena.bytes(item.name,encoding='ascii'),self.arena.bytes(item.value,encoding='latin-1'))for item in entries];array=self.arena.array(native.Header,projected);self.pointer=ctypes.cast(array,ctypes.POINTER(native.Header))if array else None;self.count=len(entries);self.cacheable=type(value)is Headers and all(type(h)is Header and type(h.name)is str and type(h.value)is str for h in entries)
+def _project_headers(value:Headers,arena:native.Arena)->tuple[ctypes._Pointer[native.Header]|None,int,bool]:
+	if not isinstance(value,Headers):raise TypeError('headers must be Headers')
+	if type(value)is Headers and not len(value):return None,0,True
+	cached=getattr(value,'_native_headers',None)
+	if type(value)is not Headers or not isinstance(cached,_PreparedHeaders):
+		cached=_PreparedHeaders(value)
+		if cached.cacheable:object.__setattr__(value,'_native_headers',cached)
+	arena.values.append(cached);return cached.pointer,cached.count,cached.cacheable
+def _copy_header(value:native.Header)->Header:return Header._from_native(native.copy_text(value.name,'ascii'),native.copy_text(value.value,'latin-1'))
+class _PreparedResponse:
+	'One response-owned, read-only ABI view and its Python buffer owners.\n\n    Core copies accepted bytes synchronously. Publication occurs only after\n    complete validation/projection. Racing first uses may build independent\n    views; each call retains its own owner until return. No shared mutation,\n    global cache, native service pointer or exchange identity is retained.\n    ';__slots__='value','arena','storage','cacheable'
+	def __init__(self,response:Response)->None:
+		'Validate and retain every input buffer before publishing this view.';self.arena=native.Arena();self.value=native.Response();status=response.status
+		if type(status)is not int or status<0 or status>=1<<32:status=_unsigned(status,32,'response.status')
+		headers,count,headers_cacheable=_project_headers(response.headers,self.arena);projection=managed_projection.PROJECTION;body=response.body
+		if projection is not None and type(body)is bytes:
+			if len(body)>native.MAX_COPY_BYTES:raise ValueError('native byte projection exceeds the Python bound')
+			if body:self.arena.values.append(body)
+			projection.prepare_response(self.value,status,headers,count,body)
+		else:_init(self.value,'coakka_http_host_response_init');self.value.status_code=status;self.value.headers,self.value.header_count=headers,count;self.value.body=self.arena.bytes(body)
+		(self.storage):native.Response|memoryview=self.value;self.cacheable=type(response)is Response and type(response.status)is int and type(response.body)is bytes and type(response.headers)is Headers and headers_cacheable
+def _prepared_response(response:Response)->_PreparedResponse:
+	'Memoize only exact immutable values; mutable/subclass inputs stay per-call.';cached=getattr(response,'_native_projection',None)
+	if type(response)is Response and isinstance(cached,_PreparedResponse):
+		if cached.storage is cached.value:cached.storage=memoryview(cached.value).toreadonly()
+		return cached
+	projected=_PreparedResponse(response)
+	if projected.cacheable:object.__setattr__(response,'_native_projection',projected)
+	return projected
+class _MetadataBudget:
+	'One call-wide byte ceiling shared by every route metadata graph.'
+	def __init__(self)->None:'Start an empty bounded projection budget.';self.bytes=0
+	def encode(self,value:object,name:str,*,binary:bool=False)->bytes:
+		'Encode one typed value once and reserve its complete byte extent.';field_limit=_MAX_METADATA_PROJECTION_BYTES if binary else _MAX_METADATA_TEXT_BYTES
+		if isinstance(value,str):
+			if str.__len__(value)>field_limit:raise ValueError(f"{name} exceeds the connector byte bound")
+			data=str.encode(value,'utf-8')
+		elif binary and type(value)is bytes:data=value
+		else:expected='bytes or str'if binary else'str';raise TypeError(f"{name} must be {expected}")
+		if len(data)>field_limit:raise ValueError(f"{name} exceeds the connector byte bound")
+		if len(data)>_MAX_METADATA_PROJECTION_BYTES-self.bytes:raise ValueError('route metadata exceeds the connector byte bound')
+		self.bytes+=len(data);return data
+class _MetadataProjection:
+	'Call-scoped native metadata graph; Core owns semantic validation.'
+	def __init__(self,arena:native.Arena,budget:_MetadataBudget)->None:'Attach every projected owner to one synchronous call arena.';self.arena=arena;self.budget=budget;self.items=0;(self.schemas):dict[int,native.ApiSchema]={}
+	def _values(self,value:tuple[_MetadataValue,...],name:str)->tuple[_MetadataValue,...]:
+		if not isinstance(value,tuple):raise TypeError(f"{name} must be a tuple")
+		self.items+=len(value)
+		if self.items>_MAX_METADATA_COLLECTION_ITEMS:raise ValueError('route metadata exceeds the connector marshalling bound')
+		return value
+	def _pointer(self,value:_NativeStructure)->ctypes._Pointer[_NativeStructure]:self.arena.values.append(value);return ctypes.pointer(value)
+	def _array(self,item_type:type[_NativeStructure],values:Sequence[_NativeStructure])->ctypes._Pointer[_NativeStructure]|None:array=self.arena.array(item_type,values);return ctypes.cast(array,ctypes.POINTER(item_type))if array else None
+	@staticmethod
+	def _bool(value:object,name:str)->int:
+		if not isinstance(value,bool):raise TypeError(f"{name} must be a bool")
+		return int(value)
+	def _text(self,value:object,name:str)->native.Bytes:'Retain one UTF-8 text value under the call-wide byte budget.';return self.arena.bytes(self.budget.encode(value,name))
+	def _example_value(self,value:object)->native.Bytes:'Retain one opaque example value under the call-wide byte budget.';return self.arena.bytes(self.budget.encode(value,'example.value',binary=True))
+	def examples(self,values:tuple[ApiExample,...])->tuple[ctypes._Pointer[native.ApiExample]|None,int]:
+		'Project one bounded example collection into arena-owned records.';projected:list[native.ApiExample]=[]
+		for source in self._values(values,'examples'):
+			if not isinstance(source,ApiExample):raise TypeError('examples must contain ApiExample values')
+			target=native.ApiExample();_init(target,'coakka_http_host_api_example_init');target.name=self._text(source.name,'example.name');target.summary=self._text(source.summary,'example.summary');target.value=self._example_value(source.value);projected.append(target)
+		return self._array(native.ApiExample,projected),len(projected)
+	def schema(self,source:ApiSchema,depth:int=1)->ctypes._Pointer[native.ApiSchema]:
+		'Project a recursive schema while retaining shared-node identity.'
+		if not isinstance(source,ApiSchema):raise TypeError('schema must be an ApiSchema')
+		if depth>_MAX_METADATA_SCHEMA_DEPTH:raise ValueError('route metadata schema exceeds the marshalling depth')
+		cached=self.schemas.get(id(source))
+		if cached is not None:return ctypes.pointer(cached)
+		target=native.ApiSchema();_init(target,'coakka_http_host_api_schema_init');self.schemas[id(source)]=target;self.arena.values.append(target)
+		if not isinstance(source.kind,ApiSchemaKind):raise TypeError('schema.kind must be an ApiSchemaKind')
+		if not isinstance(source.additional_properties,ApiAdditionalProperties):raise TypeError('schema.additional_properties must be an ApiAdditionalProperties')
+		target.kind=int(source.kind);target.format=self._text(source.format,'schema.format');target.reference=self._text(source.reference,'schema.reference');enum_values=[self._text(item,'schema.enum_values')for item in self._values(source.enum_values,'schema.enum_values')];enum_array=self.arena.array(native.Bytes,enum_values);target.enum_values=ctypes.cast(enum_array,ctypes.POINTER(native.Bytes))if enum_array else None;target.enum_value_count=len(enum_values);target.additional_properties=int(source.additional_properties)
+		if source.items is not None:target.items=self.schema(source.items,depth+1)
+		properties:list[native.ApiSchemaProperty]=[]
+		for property_value in self._values(source.properties,'schema.properties'):
+			if not isinstance(property_value,ApiSchemaProperty):raise TypeError('schema.properties must contain ApiSchemaProperty values')
+			item=native.ApiSchemaProperty();_init(item,'coakka_http_host_api_schema_property_init');item.name=self._text(property_value.name,'schema.property.name');item.description=self._text(property_value.description,'schema.property.description');item.required=self._bool(property_value.required,'schema property required');item.schema=self.schema(property_value.schema,depth+1);properties.append(item)
+		target.properties=self._array(native.ApiSchemaProperty,properties);target.property_count=len(properties)
+		if source.nullable is not None:target.has_nullable=1;target.nullable=self._bool(source.nullable,'schema.nullable')
+		return ctypes.pointer(target)
+	def media_types(self,values:tuple[ApiMediaType,...])->tuple[ctypes._Pointer[native.ApiMediaType]|None,int]:
+		'Project one bounded media-type collection and its child graphs.';projected:list[native.ApiMediaType]=[]
+		for source in self._values(values,'content'):
+			if not isinstance(source,ApiMediaType):raise TypeError('content must contain ApiMediaType values')
+			target=native.ApiMediaType();_init(target,'coakka_http_host_api_media_type_init');target.media_type=self._text(source.media_type,'media_type');target.schema=self.schema(source.schema);target.examples,target.example_count=self.examples(source.examples);projected.append(target)
+		return self._array(native.ApiMediaType,projected),len(projected)
+	def metadata(self,source:RouteApiMetadata)->ctypes._Pointer[native.RouteApiMetadata]:
+		'Build one complete borrowed metadata root for synchronous copying.'
+		if not isinstance(source,RouteApiMetadata):raise TypeError('route.api_metadata must be a RouteApiMetadata')
+		target=native.RouteApiMetadata();_init(target,'coakka_http_host_route_api_metadata_init');target.deprecated=self._bool(source.deprecated,'metadata.deprecated');target.operation_id=self._text(source.operation_id,'metadata.operation_id');target.summary=self._text(source.summary,'metadata.summary');target.description=self._text(source.description,'metadata.description');tags=[self._text(value,'metadata.tags')for value in self._values(source.tags,'tags')];tag_array=self.arena.array(native.Bytes,tags);target.tags=ctypes.cast(tag_array,ctypes.POINTER(native.Bytes))if tag_array else None;target.tag_count=len(tags);parameters:list[native.ApiParameter]=[]
+		for parameter in self._values(source.parameters,'parameters'):
+			if not isinstance(parameter,ApiParameter):raise TypeError('parameters must contain ApiParameter values')
+			if not isinstance(parameter.location,ApiParameterLocation):raise TypeError('parameter.location must be an ApiParameterLocation')
+			native_parameter=native.ApiParameter();_init(native_parameter,'coakka_http_host_api_parameter_init');native_parameter.location=int(parameter.location);native_parameter.name=self._text(parameter.name,'parameter.name');native_parameter.description=self._text(parameter.description,'parameter.description');native_parameter.schema=self.schema(parameter.schema);native_parameter.examples,native_parameter.example_count=self.examples(parameter.examples);native_parameter.required=self._bool(parameter.required,'parameter.required');parameters.append(native_parameter)
+		target.parameters=self._array(native.ApiParameter,parameters);target.parameter_count=len(parameters)
+		if source.request_body is not None:
+			if not isinstance(source.request_body,ApiRequestBody):raise TypeError('request_body must be an ApiRequestBody')
+			body=native.ApiRequestBody();_init(body,'coakka_http_host_api_request_body_init');body.required=self._bool(source.request_body.required,'request_body.required');body.description=self._text(source.request_body.description,'request_body.description');body.content,body.content_count=self.media_types(source.request_body.content);target.request_body=self._pointer(body)
+		responses:list[native.ApiResponse]=[]
+		for response in self._values(source.responses,'responses'):
+			if not isinstance(response,ApiResponse):raise TypeError('responses must contain ApiResponse values')
+			native_response=native.ApiResponse();_init(native_response,'coakka_http_host_api_response_init');native_response.selector=2 if response.status is None else 1;native_response.status_code=0 if response.status is None else _unsigned(response.status,32,'response.status');native_response.description=self._text(response.description,'response.description');headers:list[native.ApiHeader]=[]
+			for header in self._values(response.headers,'response.headers'):
+				if not isinstance(header,ApiResponseHeader):raise TypeError('response.headers must contain ApiResponseHeader values')
+				native_header=native.ApiHeader();_init(native_header,'coakka_http_host_api_header_init');native_header.name=self._text(header.name,'response.header.name');native_header.description=self._text(header.description,'response.header.description');native_header.schema=self.schema(header.schema);native_header.examples,native_header.example_count=self.examples(header.examples);headers.append(native_header)
+			native_response.headers=self._array(native.ApiHeader,headers);native_response.header_count=len(headers);native_response.content,native_response.content_count=self.media_types(response.content);responses.append(native_response)
+		target.responses=self._array(native.ApiResponse,responses);target.response_count=len(responses);requirements:list[native.ApiSecurityRequirement]=[]
+		for security in self._values(source.security_requirements,'security_requirements'):
+			if not isinstance(security,ApiSecurityRequirement):raise TypeError('security_requirements must contain ApiSecurityRequirement values')
+			requirement=native.ApiSecurityRequirement();_init(requirement,'coakka_http_host_api_security_requirement_init');uses:list[native.ApiSecurityUse]=[]
+			for use in self._values(security.uses,'security uses'):
+				if not isinstance(use,ApiSecurityUse):raise TypeError('security uses must contain ApiSecurityUse values')
+				native_use=native.ApiSecurityUse();_init(native_use,'coakka_http_host_api_security_use_init');native_use.scheme_reference=self._text(use.scheme_reference,'security.scheme_reference');scopes=[self._text(scope,'security.scope')for scope in self._values(use.scopes,'security scopes')];scope_array=self.arena.array(native.Bytes,scopes);native_use.scopes=ctypes.cast(scope_array,ctypes.POINTER(native.Bytes))if scope_array else None;native_use.scope_count=len(scopes);uses.append(native_use)
+			requirement.uses=self._array(native.ApiSecurityUse,uses);requirement.use_count=len(uses);requirements.append(requirement)
+		target.security_requirements=self._array(native.ApiSecurityRequirement,requirements);target.security_requirement_count=len(requirements);definitions:list[native.ApiSchemaDefinition]=[]
+		for definition_value in self._values(source.schema_definitions,'schema_definitions'):
+			if not isinstance(definition_value,ApiSchemaDefinition):raise TypeError('schema_definitions must contain ApiSchemaDefinition values')
+			definition=native.ApiSchemaDefinition();_init(definition,'coakka_http_host_api_schema_definition_init');definition.name=self._text(definition_value.name,'schema_definition.name');definition.schema=self.schema(definition_value.schema);definitions.append(definition)
+		target.schema_definitions=self._array(native.ApiSchemaDefinition,definitions);target.schema_definition_count=len(definitions);return self._pointer(target)
+def _native_route(value:Route,arena:native.Arena,metadata_budget:_MetadataBudget)->native.Route:
+	if not isinstance(value,Route):raise TypeError('routes must contain Route values')
+	result=native.Route();_init(result,'coakka_http_host_route_init');result.route_id=_unsigned(value.id,64,'route.id');result.handler_binding_id=_unsigned(value.handler_binding_id or value.id,64,'route.handler_binding_id')
+	if value.websocket:result.flags|=1
+	if value.body_delivery is BodyDelivery.STREAM:result.flags|=2
+	result.method=arena.bytes(value.method,encoding='ascii');result.encoded_path_pattern=arena.bytes(value.pattern);policy=value.body_policy;result.body_policy.enabled=int(policy.enabled);result.body_policy.accept_absent=int(policy.accept_absent);result.body_policy.accept_other=int(policy.accept_other);result.body_policy.accept_form_urlencoded=int(policy.accept_form_urlencoded);result.body_policy.accept_multipart_form_data=int(policy.accept_multipart_form_data);result.body_policy.max_body_bytes=_unsigned(policy.max_body_bytes,64,'body_policy.max_body_bytes')
+	if value.api_metadata is not None:result.api_metadata=_MetadataProjection(arena,metadata_budget).metadata(value.api_metadata)
+	return result
+def _project_configuration(value:RuntimeConfig)->tuple[native.Configuration,ctypes._Pointer[native.Route]|None,int,native.Arena]:
+	if not isinstance(value,RuntimeConfig):raise TypeError('configuration must be a RuntimeConfig')
+	arena=native.Arena();configuration=native.Configuration();_init(configuration,'coakka_http_host_configuration_init');execution=native.ExecutionOptions(ctypes.sizeof(native.ExecutionOptions),int(ExecutionMode.PREFER_SUPPORTED),1,0);arena.values.append(execution);configuration.execution=ctypes.pointer(execution);listener=value.listener;configuration.port=_unsigned(listener.port,16,'listener.port');configuration.protocol=int(listener.protocol);configuration.security=int(listener.security);configuration.bind_address=arena.bytes(listener.bind_address);configuration.credential_generation=_unsigned(listener.credential_generation,64,'listener.credential_generation');configuration.credential_id=arena.bytes(listener.credential_id);configuration.certificate_chain_file=arena.bytes(listener.certificate_chain_file);configuration.private_key_file=arena.bytes(listener.private_key_file);configuration.trust_roots_file=arena.bytes(listener.trust_roots_file);configuration.use_io_uring=int(value.io_backend is IoBackend.IO_URING)
+	for limit_field in fields(value.limits):
+		name=limit_field.name;native_name='max_total_segments'if name=='max_total_route_segments'else name;bits=64 if native_name in native._LIMIT_U64 or native_name=='event_loop_cpu_mask'else 32;number=_unsigned(getattr(value.limits,name),bits,name)
+		if number:setattr(configuration.limits,native_name,number)
+	for name in('reserve_websocket','omit_buffered_success_events'):
+		flag=getattr(value,name)
+		if not isinstance(flag,bool):raise TypeError(f"{name} must be a bool")
+		setattr(configuration,name,int(flag))
+	monitor=value.monitor;configuration.monitor.event_capacity=_unsigned(monitor.event_capacity,32,'monitor.event_capacity');configuration.monitor.max_events_per_read=_unsigned(monitor.max_events_per_read,32,'monitor.max_events_per_read');configuration.monitor.categories=int(monitor.categories);configuration.monitor.initial_collection=int(monitor.collection);configuration.monitor.signal_reserved=int(monitor.signal_reserved);configuration.monitor.fixed_latency_buckets=int(monitor.fixed_latency_buckets);compression=value.compression
+	if not isinstance(compression,Compression)or not isinstance(compression.mode,CompressionMode):raise TypeError('compression requires a Compression value with a CompressionMode')
+	configuration.compression.enabled=int(compression.mode is CompressionMode.GZIP)
+	if compression.mode is CompressionMode.GZIP:
+		for name in('minimum_body_bytes','maximum_body_bytes','maximum_encoded_bytes','workspace_bytes'):setattr(configuration.compression,name,_unsigned(getattr(compression,name),64,f"compression.{name}"))
+		if isinstance(compression.gzip_level,bool)or not isinstance(compression.gzip_level,int):raise TypeError('compression.gzip_level must be an integer')
+		if compression.gzip_level<-(1<<31)or compression.gzip_level>=1<<31:raise ValueError('compression.gzip_level is outside the signed 32-bit range')
+		configuration.compression.gzip_level=compression.gzip_level
+	mounts:list[native.StaticMount]=[]
+	for mount_source in value.static_mounts:
+		mount_item=native.StaticMount();_init(mount_item,'coakka_http_host_static_mount_init')
+		if mount_source.spa_fallback_file:mount_item.flags|=1
+		if mount_source.include_dotfiles:mount_item.flags|=2
+		mount_item.url_prefix=arena.bytes(mount_source.url_prefix);mount_item.root_path=arena.bytes(mount_source.root_path)
+		if mount_source.index_file:mount_item.index_file=arena.bytes(mount_source.index_file)
+		if mount_source.spa_fallback_file:mount_item.spa_fallback_file=arena.bytes(mount_source.spa_fallback_file)
+		if mount_source.cache_control:mount_item.cache_control=arena.bytes(mount_source.cache_control)
+		mounts.append(mount_item)
+	mount_array=arena.array(native.StaticMount,mounts);configuration.static_mount_count=len(mounts);configuration.static_mounts=ctypes.cast(mount_array,ctypes.POINTER(native.StaticMount))if mount_array else None
+	if value.max_total_static_assets:configuration.max_total_static_assets=_unsigned(value.max_total_static_assets,32,'max_total_static_assets')
+	authorities:list[native.FileAuthority]=[]
+	for authority_source in value.file_authorities:authority_item=native.FileAuthority();_init(authority_item,'coakka_http_host_file_authority_init');authority_item.authority_id=_unsigned(authority_source.authority_id,64,'authority_id');authority_item.root_path=arena.bytes(authority_source.root_path);authority_item.max_file_bytes=_unsigned(authority_source.max_file_bytes,64,'max_file_bytes');authority_item.max_active_files=_unsigned(authority_source.max_active_files,32,'max_active_files');authorities.append(authority_item)
+	authority_array=arena.array(native.FileAuthority,authorities);configuration.file_authority_count=len(authorities);configuration.file_authorities=ctypes.cast(authority_array,ctypes.POINTER(native.FileAuthority))if authority_array else None;endpoints_by_target:list[ctypes.Array[native.OutboundEndpoint]]=[];targets:list[native.OutboundTarget]=[]
+	for target_source in value.outbound_targets:
+		endpoints:list[native.OutboundEndpoint]=[]
+		for endpoint in target_source.endpoints:endpoint_item=native.OutboundEndpoint();_init(endpoint_item,'coakka_http_host_outbound_endpoint_init');endpoint_item.weight=_unsigned(endpoint.weight,32,'endpoint.weight');endpoint_item.node_id=arena.bytes(endpoint.node_id);endpoint_item.connect_host=arena.bytes(endpoint.connect_host);endpoint_item.connect_port=_unsigned(endpoint.connect_port,16,'endpoint.connect_port');endpoint_item.http_authority=arena.bytes(endpoint.http_authority);endpoint_item.security=int(endpoint.security);endpoint_item.available=int(endpoint.available);endpoint_item.tls_peer_identity=arena.bytes(endpoint.tls_peer_identity);endpoint_item.tls_trust_generation=_unsigned(endpoint.tls_trust_generation,64,'endpoint.tls_trust_generation');endpoint_item.tls_client_identity_generation=_unsigned(endpoint.tls_client_identity_generation,64,'endpoint.tls_client_identity_generation');endpoints.append(endpoint_item)
+		endpoint_array=arena.array(native.OutboundEndpoint,endpoints)
+		if endpoint_array:endpoints_by_target.append(endpoint_array)
+		target=native.OutboundTarget();_init(target,'coakka_http_host_outbound_target_init');target.strategy=int(target_source.strategy);target.name=arena.bytes(target_source.name);target.generation=_unsigned(target_source.generation,64,'target.generation');target.endpoints=ctypes.cast(endpoint_array,ctypes.POINTER(native.OutboundEndpoint))if endpoint_array else None;target.endpoint_count=len(endpoints);targets.append(target)
+	arena.values.extend(endpoints_by_target);target_array=arena.array(native.OutboundTarget,targets);configuration.outbound_target_count=len(targets);configuration.outbound_targets=ctypes.cast(target_array,ctypes.POINTER(native.OutboundTarget))if target_array else None;trusts:list[native.OutboundTrust]=[]
+	for trust_source in value.outbound_trusts:trust_item=native.OutboundTrust();_init(trust_item,'coakka_http_host_outbound_trust_init');trust_item.generation=_unsigned(trust_source.generation,64,'trust.generation');trust_item.ca_pem=arena.bytes(trust_source.ca_pem);trusts.append(trust_item)
+	trust_array=arena.array(native.OutboundTrust,trusts);configuration.outbound_trust_count=len(trusts);configuration.outbound_trusts=ctypes.cast(trust_array,ctypes.POINTER(native.OutboundTrust))if trust_array else None;identities:list[native.OutboundIdentity]=[]
+	for identity_source in value.outbound_identities:identity_item=native.OutboundIdentity();_init(identity_item,'coakka_http_host_outbound_identity_init');identity_item.generation=_unsigned(identity_source.generation,64,'identity.generation');identity_item.certificate_chain_pem=arena.bytes(identity_source.certificate_chain_pem);identity_item.private_key_pem=arena.bytes(identity_source.private_key_pem);identities.append(identity_item)
+	identity_array=arena.array(native.OutboundIdentity,identities);configuration.outbound_identity_count=len(identities);configuration.outbound_identities=ctypes.cast(identity_array,ctypes.POINTER(native.OutboundIdentity))if identity_array else None;metadata_budget=_MetadataBudget();routes=[_native_route(route,arena,metadata_budget)for route in value.routes];route_array=arena.array(native.Route,routes);route_pointer=ctypes.cast(route_array,ctypes.POINTER(native.Route))if route_array else None;return configuration,route_pointer,len(routes),arena
+def features()->Capability:"Read the loaded Core image's capabilities without probing the OS.";return Capability(native.LIBRARY.library.coakka_http_host_features())
+def inspect_runtime()->RuntimeInspection:'Pull global Core facts, including its bounded optional-backend probe.';value=native.RuntimeInspection();_init(value,'coakka_http_host_runtime_info_init');native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_runtime_inspect(ctypes.byref(value)));return RuntimeInspection(abi_version=int(value.abi_version),features=Capability(value.features),io_uring_compiled=bool(value.io_uring_compiled),io_uring_probed=bool(value.io_uring_probed),io_uring_supported=bool(value.io_uring_supported),io_uring_probe_error=int(value.io_uring_probe_error))
+def plan_service(required_capabilities:Capability,adapter_capabilities:Capability=Capability.ALL)->ServicePlan:
+	'Validate capability dependencies without probing the operating system.';request=native.ServicePlanRequest();result=native.ServicePlan();_init(request,'coakka_http_host_service_plan_request_init');_init(result,'coakka_http_host_service_plan_init');request.required_capabilities=int(required_capabilities);request.adapter_capabilities=int(adapter_capabilities);status=native.LIBRARY.library.coakka_http_host_plan_service(ctypes.byref(request),ctypes.byref(result))
+	if status not in(native.STATUS_OK,9):native.LIBRARY.check(status)
+	return ServicePlan(supported=bool(result.supported),required_capabilities=Capability(result.required_capabilities),adapter_capabilities=Capability(result.adapter_capabilities),missing_capabilities=Capability(result.missing_capabilities))
+@dataclass(frozen=True,slots=True)
+class InspectionOptions:'Startup intent for authenticated runtime inspection.';bearer_file:str;runtime_instance_id:int;runtime_generation:int;allow_plaintext_loopback:bool|None=None
+def _project_inspection(value:InspectionOptions,arena:native.Arena)->native.InspectionOptions:
+	if not isinstance(value,InspectionOptions):raise TypeError('inspection must be an InspectionOptions')
+	result=native.InspectionOptions();_init(result,'coakka_http_host_inspection_options_init');result.runtime_instance_id=_unsigned(value.runtime_instance_id,64,'runtime_instance_id');result.runtime_generation=_unsigned(value.runtime_generation,64,'runtime_generation');result.bearer_file=arena.bytes(value.bearer_file)
+	if value.allow_plaintext_loopback is not None:
+		if not isinstance(value.allow_plaintext_loopback,bool):raise TypeError('allow_plaintext_loopback must be a bool or None')
+		result.allow_plaintext_loopback=int(value.allow_plaintext_loopback)
+	return result
+class Runtime:
+	'Lifecycle owner for one callback-free native HTTP runtime instance.'
+	def __init__(self,configuration:RuntimeConfig=RuntimeConfig(),*,inspection:InspectionOptions|None=None)->None:
+		'Validate and copy one complete configuration into native ownership.';projected,routes,route_count,arena=_project_configuration(configuration);service=ctypes.c_void_p();failed_index=ctypes.c_uint32(_FAILED_INDEX_NONE);library=native.LIBRARY.library;arguments=routes,route_count,ctypes.byref(service),ctypes.byref(failed_index)
+		if inspection is None:status=library.coakka_http_host_service_create(ctypes.byref(projected),*arguments)
+		else:native.LIBRARY.bind_inspection_startup();options=_project_inspection(inspection,arena);status=library.coakka_http_host_service_create_with_inspection(ctypes.byref(projected),ctypes.byref(options),*arguments)
+		del arena
+		if status!=native.STATUS_OK:
+			try:native.LIBRARY.check(status)
+			except NativeError as error:
+				if failed_index.value!=_FAILED_INDEX_NONE:raise NativeError(error.status,f"route {failed_index.value}: {error}",item_index=int(failed_index.value))from error
+				raise
+		if not service.value:raise RuntimeError('native runtime returned an empty service')
+		self._service=service;self._condition=threading.Condition();self._lifecycle=threading.Lock();self._request_reader=threading.Lock();self._request_event=native.RequestEvent();_init(self._request_event,'coakka_http_host_request_event_init');self._request_event_pointer=ctypes.pointer(self._request_event);self._request_event_address=ctypes.addressof(self._request_event);self._request_view=native.RequestView();_init(self._request_view,'coakka_http_host_request_view_init');self._request_view_pointer=ctypes.pointer(self._request_view);self._request_header=native.Header();self._request_header_pointer=ctypes.pointer(self._request_header);self._websocket_reader=threading.Lock();self._outbound_reader=threading.Lock();self._monitor_waiter=threading.Lock();self._active=0;self._closing=False;projection=managed_projection.PROJECTION;self._service_record_factory=None if projection is None else projection.service_record
+	@contextmanager
+	def _borrow(self)->Iterator[ctypes.c_void_p]:
+		with self._condition:
+			if not self._service.value or self._closing:raise RuntimeError('runtime is closing or closed')
+			self._active+=1;service=self._service
+		try:yield service
+		finally:
+			with self._condition:
+				self._active-=1
+				if not self._active:self._condition.notify_all()
+	@property
+	def capabilities(self)->Capability:"Return the loaded Core image's immutable capability matrix.";return features()
+	def info(self)->RuntimeInfo:
+		'Copy backend request, probe, fallback, and lifecycle facts.';value=native.ServiceInfo();_init(value,'coakka_http_host_service_info_init')
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_service_info(service,ctypes.byref(value)))
+		return RuntimeInfo(abi_version=int(value.abi_version),io_uring_requested=bool(value.io_uring_requested),io_uring_effective=bool(value.io_uring_effective),io_uring_compiled=bool(value.io_uring_compiled),io_uring_probed=bool(value.io_uring_probed),io_uring_supported=bool(value.io_uring_supported),service_started=bool(value.service_started),fallback_reason=IoBackendFallbackReason(value.io_fallback_reason),io_uring_probe_error=int(value.io_uring_probe_error),request_notification_batch_size=int(value.request_notification_batch_size),event_loop_cpu_mask=int(value.event_loop_cpu_mask),event_loop_cpu_mask_supported=bool(value.event_loop_cpu_mask_supported),event_loop_cpu_mask_applied=bool(value.event_loop_cpu_mask_applied),terminal_notification_batch_size=int(value.terminal_notification_batch_size),execution=ExecutionInfo(selection=ExecutionSelection(requested_mode=ExecutionMode(value.selection.requested_mode),requested_count=int(value.selection.requested_count),selected_count=int(value.selection.selected_count),reason=ExecutionReason(value.selection.reason)),configured_event_loops=int(value.execution.configured_event_loops),active_event_loops=int(value.execution.active_event_loops),draining_event_loops=int(value.execution.draining_event_loops),failed_event_loops=int(value.execution.failed_event_loops),observed=bool(value.execution.observed)))
+	runtime_info=info
+	def effective_limits(self)->Limits:
+		"Copy Core's accepted startup limits; never reconstruct defaults.";value=native.Limits();_init(value,'coakka_http_host_limits_init')
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_service_limits(service,ctypes.byref(value)))
+		projected:dict[str,int]={}
+		for limit_field in fields(Limits):
+			name=limit_field.name;target='max_total_segments'if name=='max_total_route_segments'else name;number=int(getattr(value,target))
+			if name.endswith('_notification_profile'):
+				try:number=NotificationProfile(number)
+				except ValueError:pass
+			projected[name]=number
+		return Limits(**projected)
+	def wait_drained(self,timeout_ms:int=0)->DrainOutcome:
+		"Observe Core's drain barrier while readers/handlers keep progressing.\n\n        This never stops Core or frees leases. A finite caller wait may return\n        PENDING; EXPIRED is Core's terminal outcome and must not become success.\n        ";timeout=_unsigned(timeout_ms,64,'timeout_ms')
+		if timeout>_MAX_WAIT_MS:raise ValueError('drain wait exceeds the 60-second bound')
+		state=ctypes.c_uint32()
+		with self._lifecycle,self._borrow()as service:status=native.LIBRARY.library.coakka_http_host_service_wait_drained(service,timeout,ctypes.byref(state))
+		try:outcome:DrainState|int=DrainState(state.value)
+		except ValueError:outcome=state.value
+		return DrainOutcome(int(status),outcome)
+	def start(self)->None:
+		'Bind the listener and start native admission.'
+		with self._lifecycle,self._borrow()as service:issue=native.Issue();_init(issue,'coakka_http_host_issue_init');native.LIBRARY.check_issue(native.LIBRARY.library.coakka_http_host_service_start(service,ctypes.byref(issue)),issue)
+	@property
+	def port(self)->int:
+		'Return the selected listener port after startup.';value=ctypes.c_uint16()
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_service_port(service,ctypes.byref(value)))
+		return int(value.value)
+	def drain(self)->None:
+		'Begin Core drain; use wait_drained to observe completion separately.'
+		with self._lifecycle,self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_service_begin_drain(service))
+	def stop(self)->None:
+		'Perform the bounded idempotent stop transition.'
+		with self._lifecycle,self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_service_stop(service))
+	def interrupt(self)->None:
+		'Wake the sole inbound reader without creating an event.'
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_interrupt_requests(service))
+	def interrupt_outbound(self)->None:
+		'Wake the sole outbound reader without creating an event.'
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_interrupt_outbound(service))
+	def close(self)->None:
+		'Force cleanup after borrowers return; retain the owner on refusal.\n\n        This is not a graceful-drain certificate. Service.close owns that policy;\n        low-level callers use drain/wait_drained explicitly before this cleanup.\n        '
+		with self._lifecycle:
+			with self._condition:
+				if not self._service.value:return
+				self._closing=True;service=self._service
+			try:
+				native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_service_stop(service))
+				with self._condition:
+					while self._active:self._condition.wait()
+				native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_service_destroy(ctypes.byref(self._service)))
+			finally:
+				with self._condition:self._closing=False;self._condition.notify_all()
+	def __enter__(self)->Self:'Return this open runtime for scoped synchronous ownership.';return self
+	def __exit__(self,_type:object,_value:object,_traceback:object)->None:'Close the runtime when its ownership scope ends.';self.close()
+	def take_event(self,timeout_ms:int=0)->Event|None:
+		'Wait for and copy one inbound event, releasing its lease exactly once.'
+		with self._request_reader,self._borrow()as service:return self._take_borrowed_event(service,_timeout(timeout_ms))
+	@contextmanager
+	def _service_event_reader(self)->Iterator[ctypes.c_void_p]:
+		"Hold the managed reader's native owner for its whole serialized loop."
+		with self._request_reader,self._borrow()as service:
+			try:yield service
+			except BaseException as failure:
+				try:self._release_retained_reader_event(service)
+				except BaseException as cleanup:raise BaseExceptionGroup('request projection and lease retirement failed',[failure,cleanup])from None
+				raise
+			else:self._release_retained_reader_event(service)
+	def _release_retained_reader_event(self,service:ctypes.c_void_p)->None:
+		'Retry only a Core event still retained after a release refusal.'
+		if self._request_event.kind!=0:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_release_request(service,self._request_event_pointer))
+	def _take_service_event_borrowed(self,service:ctypes.c_void_p)->Event|_ServiceRequestEvent|None:
+		'Take one managed event while `_service_event_reader` owns the borrow.';projection=managed_projection.PROJECTION
+		if projection is None:raise RuntimeError('managed service requires its native projection image')
+		address=service.value
+		if address is None:raise RuntimeError('native runtime returned an empty service')
+		return self._copy_projected_service_event(projection.take(self,address,self._request_event_address))
+	def _copy_projected_headers(self,values:tuple[str,...]|None)->Headers:
+		'Build immutable Header values from one native-owned flat tuple.'
+		if values is None:return _EMPTY_HEADERS
+		projection=managed_projection.PROJECTION
+		if projection is None:raise RuntimeError('managed headers require their native projection image')
+		return projection.headers(values)
+	def _copy_projected_service_event(self,raw:_ProjectedValues)->Event|_ServiceRequestEvent|None:
+		'Project one private owning native tuple into the public value graph.';status=cast(int,raw[0])
+		if status==native.STATUS_TIMEOUT:return None
+		native.LIBRARY.check(status);projected=cast(_ProjectedSuccess,raw);kind=projected[1];sequence=projected[4];handler_binding_id=projected[5]
+		if kind==_REQUEST_EVENT_KIND:
+			constructor=self._service_record_factory
+			if constructor is None:raise RuntimeError('managed service requires its native projection image')
+			return constructor(raw)
+		exchange=ExchangeId(projected[2],projected[3]);event_values=cast(_ProjectedEvent,projected);return Event(kind=EventKind(kind),exchange=exchange,sequence=sequence,handler_binding_id=handler_binding_id,data=event_values[6]or b'',stream_trailers=self._copy_projected_headers(event_values[7]))
+	def _take_borrowed_event(self,service:ctypes.c_void_p,native_timeout:int)->Event|None:
+		'Own one take/release law under a caller-proven Runtime borrow.';value=self._request_event;status=native.LIBRARY.library.coakka_http_host_take_request(service,native_timeout,self._request_event_pointer)
+		if status==native.STATUS_TIMEOUT:return None
+		native.LIBRARY.check(status)
+		try:return self._copy_event(service,value)
+		finally:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_release_request(service,self._request_event_pointer))
+	def _copy_inbound_headers(self,count:int,item_name:str)->Headers:
+		'Reuse sole-reader ABI descriptors while returning only owned values.'
+		if count>_MAX_HEADER_COUNT:raise RuntimeError('native header count exceeds the Python bound')
+		if count==0:return _EMPTY_HEADERS
+		project=getattr(native.LIBRARY.library,item_name);values:list[Header]=[]
+		for index in range(count):
+			if not project(self._request_event_pointer,index,self._request_header_pointer):raise RuntimeError('native header projection rejected a declared index')
+			values.append(_copy_header(self._request_header))
+		return Headers._from_native(tuple(values))
+	def _copy_event(self,service:ctypes.c_void_p,value:native.RequestEvent)->Event:kind=EventKind(value.kind);exchange=ExchangeId(int(value.exchange.slot),int(value.exchange.generation));data=native.copy_bytes(value.data)if kind is EventKind.REQUEST_DATA else b'';request=self._copy_request(service,value,exchange)if kind is EventKind.REQUEST else None;trailers=self._copy_inbound_headers(int(native.LIBRARY.library.coakka_http_host_request_stream_trailer_count(self._request_event_pointer)),'coakka_http_host_request_stream_trailer')if kind is EventKind.REQUEST_TRAILERS else _EMPTY_HEADERS;return Event(kind=kind,exchange=exchange,sequence=int(value.sequence),handler_binding_id=int(value.handler_binding_id),data=data,request=request,stream_trailers=trailers)
+	def _copy_request(self,service:ctypes.c_void_p,value:native.RequestEvent,exchange:ExchangeId)->Request:
+		library=native.LIBRARY.library;view=self._request_view;native.LIBRARY.check(library.coakka_http_host_request_view(self._request_event_pointer,self._request_view_pointer));path_count=int(view.path_parameter_count);query_count=int(view.query_parameter_count)
+		if path_count>_MAX_ITEMS or query_count>_MAX_ITEMS:raise RuntimeError('native request parameter count exceeds the Python bound')
+		paths:list[PathParameter]=[]
+		for index in range(path_count):
+			path_item=native.PathParameter()
+			if not library.coakka_http_host_request_path_parameter(self._request_event_pointer,index,ctypes.byref(path_item)):raise RuntimeError('native path parameter projection failed')
+			paths.append(PathParameter(native.copy_text(path_item.name,'utf-8'),native.copy_text(path_item.encoded_value,'utf-8')))
+		queries:list[QueryParameter]=[]
+		for index in range(query_count):
+			query_item=native.QueryParameter()
+			if not library.coakka_http_host_request_query_parameter(self._request_event_pointer,index,ctypes.byref(query_item)):raise RuntimeError('native query parameter projection failed')
+			queries.append(QueryParameter(native.copy_text(query_item.encoded_key,'utf-8'),native.copy_text(query_item.encoded_value,'utf-8'),bool(query_item.has_value)))
+		cancelled=ctypes.c_uint8();native.LIBRARY.check(library.coakka_http_host_request_cancelled(service,value.exchange,ctypes.byref(cancelled)));return Request(exchange=exchange,method=native.copy_text(view.method,'ascii'),scheme=native.copy_text(view.scheme,'ascii'),authority=native.copy_text(view.authority,'latin-1'),target=native.copy_text(view.target,'latin-1'),headers=self._copy_inbound_headers(int(view.header_count),'coakka_http_host_request_header'),body=native.copy_bytes(view.body),body_delivery=BodyDelivery(view.body_delivery),route_id=int(view.route_id),route_generation=int(view.route_generation),binding_revision=int(view.binding_revision),handler_binding_id=int(value.handler_binding_id),path_parameters=tuple(paths),query_parameters=tuple(queries),trailers=self._copy_inbound_headers(int(view.trailer_count),'coakka_http_host_request_trailer'),cancelled=bool(cancelled.value))
+	def exchange_cancelled(self,exchange:ExchangeId)->bool:
+		'Return current cancellation truth for an admitted exchange.';result=ctypes.c_uint8()
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_request_cancelled(service,_native_exchange(exchange),ctypes.byref(result)))
+		return bool(result.value)
+	def respond(self,exchange:ExchangeId,response:Response)->None:
+		'Copy and submit one buffered response.'
+		if not isinstance(response,Response):raise TypeError('response must be a Response')
+		projected=_prepared_response(response)
+		with self._borrow()as service:
+			projection=managed_projection.PROJECTION
+			if projection is None:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_respond(service,_native_exchange(exchange),ctypes.byref(projected.value)));return
+			if not isinstance(exchange,ExchangeId):raise TypeError('exchange must be an ExchangeId')
+			address=service.value
+			if address is None:raise RuntimeError('native runtime returned an empty service')
+			native.LIBRARY.check(projection.respond(projected,address,exchange.slot,exchange.generation,projected.storage))
+	def respond_file(self,exchange:ExchangeId,response:FileResponse)->None:
+		'Serve one application-selected path under a configured authority.'
+		if not isinstance(response,FileResponse):raise TypeError('response must be a FileResponse')
+		arena=native.Arena();value=native.FileResponse();_init(value,'coakka_http_host_file_response_init');value.head.status_code=_unsigned(response.status,32,'response.status');value.head.headers,value.head.header_count,_headers_cacheable=_project_headers(response.headers,arena);value.authority_id=_unsigned(response.authority_id,64,'authority_id');value.encoded_path=arena.bytes(response.encoded_path)
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_respond_file(service,_native_exchange(exchange),ctypes.byref(value)))
+	def fail(self,exchange:ExchangeId,failure:Failure)->None:
+		'Terminalize one exchange with a typed failure.'
+		if not isinstance(failure,Failure):raise TypeError('failure must be a Failure')
+		arena=native.Arena();value=native.Failure();_init(value,'coakka_http_host_failure_init');value.reason=_unsigned(failure.reason,32,'failure.reason');value.detail=arena.bytes(failure.detail)
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_fail(service,_native_exchange(exchange),ctypes.byref(value)))
+	def start_response_stream(self,exchange:ExchangeId,head:Response)->None:
+		'Submit a response head for an application-driven stream.';arena=native.Arena();value=native.Response();_init(value,'coakka_http_host_response_init');value.status_code=_unsigned(head.status,32,'response.status');value.headers,value.header_count,_headers_cacheable=_project_headers(head.headers,arena)
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_start_response_stream(service,_native_exchange(exchange),ctypes.byref(value)))
+	def write_response_stream(self,exchange:ExchangeId,data:bytes)->None:
+		'Copy one response-stream chunk after writable credit.';arena=native.Arena();value=arena.bytes(data)
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_write_response_stream(service,_native_exchange(exchange),value))
+	def finish_response_stream(self,exchange:ExchangeId,trailers:Headers=Headers())->None:
+		'Finish one response stream with copied optional trailers.';arena=native.Arena();values,count,_headers_cacheable=_project_headers(trailers,arena)
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_finish_response_stream(service,_native_exchange(exchange),values,count))
+	def start_sse(self,exchange:ExchangeId,headers:Headers=Headers())->None:
+		'Start one native-serialized server-sent event response.';arena=native.Arena();values,count,_headers_cacheable=_project_headers(headers,arena)
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_start_sse(service,_native_exchange(exchange),values,count))
+	def write_sse(self,exchange:ExchangeId,event:SseEvent)->None:
+		'Copy one structured server-sent event.';arena=native.Arena();value=native.SseEvent();_init(value,'coakka_http_host_sse_event_init');value.data=arena.bytes(event.data)
+		if event.event_type is not None:value.event_type=arena.bytes(event.event_type);value.has_event_type=1
+		if event.id is not None:value.id=arena.bytes(event.id);value.has_id=1
+		if event.retry_ms is not None:value.retry_ms=_unsigned(event.retry_ms,64,'event.retry_ms');value.has_retry=1
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_write_sse(service,_native_exchange(exchange),ctypes.byref(value)))
+	def accept_websocket(self,exchange:ExchangeId,subprotocol:str='')->None:
+		'Accept a declared WebSocket route with an optional subprotocol.';arena=native.Arena();value=arena.bytes(subprotocol,encoding='ascii')
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_accept_websocket(service,_native_exchange(exchange),value))
+	def take_websocket(self,timeout_ms:int=0)->WebSocketEvent|None:
+		'Wait for and copy one WebSocket event, then release its lease.';value=native.WebSocketEvent();_init(value,'coakka_http_host_websocket_event_init')
+		with self._websocket_reader,self._borrow()as service:
+			status=native.LIBRARY.library.coakka_http_host_take_websocket(service,_timeout(timeout_ms),ctypes.byref(value))
+			if status==native.STATUS_TIMEOUT:return None
+			native.LIBRARY.check(status)
+			try:return WebSocketEvent(kind=WebSocketEventKind(value.kind),session=WebSocketId(int(value.session.slot),int(value.session.generation)),origin_exchange=ExchangeId(int(value.origin_exchange.slot),int(value.origin_exchange.generation)),close_code=int(value.close_code),data=native.copy_bytes(value.data))
+			finally:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_release_websocket(service,ctypes.byref(value)))
+	def send_websocket(self,session:WebSocketId,kind:WebSocketEventKind,data:bytes)->None:
+		'Copy one ordered WebSocket text, binary, ping, or pong frame.';arena=native.Arena()
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_send_websocket(service,_native_websocket(session),int(kind),arena.bytes(data)))
+	def close_websocket(self,session:WebSocketId,code:int=1000,reason:bytes=b'')->None:
+		'Start one ordered WebSocket close handshake.';arena=native.Arena()
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_close_websocket(service,_native_websocket(session),_unsigned(code,32,'close code'),arena.bytes(reason)))
+	def outbound_submit(self,request:OutboundRequest)->OutboundId:
+		'Submit one buffered call to a startup-declared logical target.'
+		if not isinstance(request,OutboundRequest):raise TypeError('request must be an OutboundRequest')
+		arena=native.Arena();value=native.OutboundRequest();call=native.OutboundCall();_init(value,'coakka_http_host_outbound_request_init');value.timeout_ms=_unsigned(request.timeout_ms,32,'request.timeout_ms');value.logical_target=arena.bytes(request.logical_target);value.method=arena.bytes(request.method,encoding='ascii');value.target=arena.bytes(request.target);value.headers,value.header_count,_headers_cacheable=_project_headers(request.headers,arena);value.body=arena.bytes(request.body)
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_submit_outbound(service,ctypes.byref(value),ctypes.byref(call)))
+		return OutboundId(int(call.slot),int(call.generation))
+	def outbound_cancel(self,call:OutboundId)->None:
+		'Request cancellation of one admitted outbound call.'
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_cancel_outbound(service,_native_outbound(call)))
+	def take_outbound(self,timeout_ms:int=0)->OutboundTerminal|None:
+		'Wait for and copy one outbound terminal, then release its lease.';value=native.OutboundEvent();_init(value,'coakka_http_host_outbound_event_init')
+		with self._outbound_reader,self._borrow()as service:
+			status=native.LIBRARY.library.coakka_http_host_take_outbound(service,_timeout(timeout_ms),ctypes.byref(value))
+			if status==native.STATUS_TIMEOUT:return None
+			native.LIBRARY.check(status)
+			try:
+				if value.response_header_count>_MAX_HEADER_COUNT:raise RuntimeError('outbound header count exceeds the Python bound')
+				headers:list[Header]=[]
+				for index in range(value.response_header_count):
+					item=native.Header()
+					if not native.LIBRARY.library.coakka_http_host_outbound_header(service,ctypes.byref(value),index,ctypes.byref(item)):raise RuntimeError('native outbound header projection failed')
+					headers.append(_copy_header(item))
+				return OutboundTerminal(reason=OutboundReason(value.reason),call=OutboundId(int(value.call.slot),int(value.call.generation)),logical_target=native.copy_bytes(value.logical_target).decode('utf-8'),target_generation=int(value.target_generation),selected_node_id=native.copy_bytes(value.selected_node_id).decode('utf-8'),phase=OutboundPhase(value.phase),retry=OutboundRetry(value.retry),certainty=OutboundCertainty(value.certainty),response_status=int(value.response_status),provider_code=int(value.provider_code),response_headers=Headers(headers),response_body=native.copy_bytes(value.response_body),diagnostic=native.copy_bytes(value.diagnostic).decode('utf-8',errors='replace'))
+			finally:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_release_outbound(service,ctypes.byref(value)))
+	@staticmethod
+	def _copy_health(value:native.Health)->Health:return Health(lifecycle=int(value.lifecycle),snapshot_sequence=int(value.snapshot_sequence),observed_monotonic_ns=int(value.observed_monotonic_ns),progress_sequence=int(value.progress_sequence),progress_monotonic_ns=int(value.progress_monotonic_ns),acknowledged_probe_sequence=int(value.acknowledged_probe_sequence),acknowledged_probe_monotonic_ns=int(value.acknowledged_probe_monotonic_ns),route_generation=int(value.route_generation),metadata_generation=int(value.metadata_generation),binding_change_sequence=int(value.binding_change_sequence),ready=bool(value.ready),admission_open=bool(value.admission_open),activity=Activity(active_requests=int(value.activity.active_requests),pending_requests=int(value.activity.pending_requests),active_connections=int(value.activity.active_connections),websocket_sessions=int(value.activity.websocket_sessions),outbound_pending=int(value.activity.outbound_pending)))
+	def health(self)->Health:
+		'Copy the current pointer-free health snapshot.';value=native.Health();_init(value,'coakka_http_host_health_init')
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_service_health(service,ctypes.byref(value)))
+		return self._copy_health(value)
+	def probe_liveness(self,timeout_ms:int=1000)->Health:
+		'Wait for fresh native progress evidence within a finite bound.';value=native.Health();_init(value,'coakka_http_host_health_init')
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_probe_liveness(service,_timeout(timeout_ms),ctypes.byref(value)))
+		return self._copy_health(value)
+	def route_snapshot(self)->RouteSnapshot:
+		'Copy one coherent structural generation and binding-table cut.';capacity=self.effective_limits().max_routes
+		if not 0<=capacity<=_MAX_ITEMS:raise RuntimeError('route snapshot exceeds the Python bound')
+		identity=native.RouteIdentity();_init(identity,'coakka_http_host_route_identity_init');values=(native.RouteState*capacity)()
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_route_snapshot(service,values if capacity else None,capacity,ctypes.byref(identity)))
+		if identity.route_count>capacity:raise RuntimeError('route snapshot returned an invalid extent')
+		return RouteSnapshot(identity=RouteIdentity(route_count=int(identity.route_count),route_generation=int(identity.route_generation),metadata_generation=int(identity.metadata_generation),binding_change_sequence=int(identity.binding_change_sequence)),routes=tuple(RouteState(route_id=int(item.route_id),handler_binding_id=int(item.handler_binding_id),binding_revision=int(item.binding_revision))for item in islice(values,identity.route_count)))
+	@staticmethod
+	def _copy_retirement(value:native.RequestRetirement)->RequestRetirement:return RequestRetirement(state=RequestRetirementState(value.state),code=RequestRetirementCode(value.code),quiescent_sources=int(value.quiescent_sources),sources=int(value.sources))
+	def rebind(self,request:RouteRebind)->RouteRebindOutcome:
+		'Apply a generation-checked handler-binding change.';value=native.RebindRequest();outcome=native.RebindOutcome();_init(value,'coakka_http_host_rebind_request_init');_init(outcome,'coakka_http_host_rebind_outcome_init');value.activation_id=_unsigned(request.activation_id,64,'activation_id');value.expected_route_generation=_unsigned(request.expected_route_generation,64,'expected_route_generation');value.route_id=_unsigned(request.route_id,64,'route_id');value.expected_binding_revision=_unsigned(request.expected_binding_revision,64,'expected_binding_revision');value.new_handler_binding_id=_unsigned(request.new_handler_binding_id,64,'new_handler_binding_id')
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_rebind(service,ctypes.byref(value),ctypes.byref(outcome)))
+		return RouteRebindOutcome(code=ControlCode(outcome.code),activation_id=int(outcome.activation_id),operation_digest=int(outcome.operation_digest),route_generation=int(outcome.route_generation),binding_change_sequence=int(outcome.binding_change_sequence),route_id=int(outcome.route_id),previous_handler_binding_id=int(outcome.previous_handler_binding_id),previous_binding_revision=int(outcome.previous_binding_revision),effective_handler_binding_id=int(outcome.effective_handler_binding_id),effective_binding_revision=int(outcome.effective_binding_revision),changed=bool(outcome.changed),replayed=bool(outcome.replayed),request_retirement=self._copy_retirement(outcome.request_retirement))
+	def publish_routes(self,publication:RoutePublication)->RoutePublicationOutcome:
+		'Atomically publish one complete structural route generation.';arena=native.Arena();metadata_budget=_MetadataBudget();routes=[_native_route(item,arena,metadata_budget)for item in publication.routes];route_array=arena.array(native.Route,routes);value=native.PublicationRequest();outcome=native.PublicationOutcome();_init(value,'coakka_http_host_publication_request_init');_init(outcome,'coakka_http_host_publication_outcome_init');value.route_count=len(routes);value.activation_id=_unsigned(publication.activation_id,64,'activation_id');value.expected_route_generation=_unsigned(publication.expected_route_generation,64,'expected_route_generation');value.expected_metadata_generation=_unsigned(publication.expected_metadata_generation,64,'expected_metadata_generation');value.expected_binding_change_sequence=_unsigned(publication.expected_binding_change_sequence,64,'expected_binding_change_sequence');value.routes=ctypes.cast(route_array,ctypes.POINTER(native.Route))if route_array else None
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_publish_routes(service,ctypes.byref(value),ctypes.byref(outcome)))
+		return RoutePublicationOutcome(code=ControlCode(outcome.code),activation_id=int(outcome.activation_id),operation_digest=int(outcome.operation_digest),previous_route_generation=int(outcome.previous_route_generation),previous_metadata_generation=int(outcome.previous_metadata_generation),previous_binding_change_sequence=int(outcome.previous_binding_change_sequence),effective_route_generation=int(outcome.effective_route_generation),effective_metadata_generation=int(outcome.effective_metadata_generation),effective_binding_change_sequence=int(outcome.effective_binding_change_sequence),actual=int(outcome.actual),limit=int(outcome.limit),route_count=int(outcome.route_count),rejected_route_index=int(outcome.rejected_route_index),changed=bool(outcome.changed),replayed=bool(outcome.replayed),request_retirement=self._copy_retirement(outcome.request_retirement))
+	@staticmethod
+	def _copy_monitor_policy(value:native.MonitorPolicy)->MonitorPolicy:return MonitorPolicy(collection=value.collection,notification=value.notification,latency=value.latency,active_event_capacity=int(value.active_event_capacity),aggregate_categories=MonitorCategory(value.aggregate_categories),event_categories=MonitorCategory(value.event_categories))
+	@classmethod
+	def _copy_monitor_config(cls,value:native.MonitorConfig)->MonitorConfig:return MonitorConfig(generation=int(value.generation),collection_epoch=int(value.collection_epoch),change_sequence=int(value.change_sequence),epoch_started_monotonic_ns=int(value.epoch_started_monotonic_ns),policy_applied_monotonic_ns=int(value.policy_applied_monotonic_ns),supported_categories=MonitorCategory(value.supported_categories),reserved_event_capacity=int(value.reserved_event_capacity),max_events_per_read=int(value.max_events_per_read),signal_reserved=bool(value.signal_reserved),fixed_latency_buckets=bool(value.fixed_latency_buckets),policy=cls._copy_monitor_policy(value.policy))
+	@staticmethod
+	def _copy_tls_credentials(value:native.TlsCredentials)->TlsCredentials:
+		security:TransportSecurity|int=int(value.security)
+		try:security=TransportSecurity(security)
+		except ValueError:pass
+		return TlsCredentials(security=security,reload_mode=TlsReloadMode(value.reload_mode),retired_generations=int(value.retired_generations),maximum_retired_generations=int(value.maximum_retired_generations),closed=bool(value.closed),preparing=bool(value.preparing),generation=int(value.generation),drain_before_generation=int(value.drain_before_generation),credential_id=bytes(value.credential_id).decode('ascii'))
+	def tls_credentials(self)->TlsCredentials:
+		"Read the secure listener's effective credential generation.";native.LIBRARY.bind_tls_control();value=native.TlsCredentials();_init(value,'coakka_http_host_tls_credentials_init')
+		with self._lifecycle,self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_tls_credentials(service,ctypes.byref(value)))
+		return self._copy_tls_credentials(value)
+	def tls_reload(self,request:TlsReloadRequest)->TlsReloadOutcome:
+		"Prepare credentials and return Core's typed publication outcome."
+		if not isinstance(request,TlsReloadRequest):raise TypeError('request must be a TlsReloadRequest')
+		native.LIBRARY.bind_tls_control();value=native.TlsReloadRequest();outcome=native.TlsReloadOutcome();_init(value,'coakka_http_host_tls_reload_request_init');_init(outcome,'coakka_http_host_tls_reload_outcome_init');arena=native.Arena();value.mode=_unsigned(request.mode,32,'mode');value.security=_unsigned(request.security,32,'security');value.expected_generation=_unsigned(request.expected_generation,64,'expected_generation');value.credential_generation=_unsigned(request.credential_generation,64,'credential_generation');value.credential_id=arena.bytes(request.credential_id);value.certificate_chain_file=arena.bytes(request.certificate_chain_file);value.private_key_file=arena.bytes(request.private_key_file);value.trust_roots_file=arena.bytes(request.trust_roots_file)
+		with self._lifecycle,self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_tls_reload(service,ctypes.byref(value),ctypes.byref(outcome)))
+		return TlsReloadOutcome(reason=TlsReloadReason(outcome.reason),changed=bool(outcome.changed),effective=self._copy_tls_credentials(outcome.effective))
+	def monitor_config(self)->MonitorConfig:
+		'Copy the complete effective monitor configuration.';value=native.MonitorConfig();_init(value,'coakka_http_host_monitor_config_init')
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_monitor_config(service,ctypes.byref(value)))
+		return self._copy_monitor_config(value)
+	def monitor_apply(self,expected_generation:int,policy:MonitorPolicy)->MonitorApplyOutcome:
+		'Apply a live policy and return accepted or rejected effective truth.';value=native.MonitorPolicy();outcome=native.MonitorApplyOutcome();_init(value,'coakka_http_host_monitor_policy_init');_init(outcome,'coakka_http_host_monitor_apply_outcome_init');value.collection=int(policy.collection);value.notification=int(policy.notification);value.latency=int(policy.latency);value.active_event_capacity=_unsigned(policy.active_event_capacity,32,'active_event_capacity');value.aggregate_categories=int(policy.aggregate_categories);value.event_categories=int(policy.event_categories)
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_monitor_apply(service,_unsigned(expected_generation,64,'expected_generation'),ctypes.byref(value),ctypes.byref(outcome)))
+		return MonitorApplyOutcome(reason=MonitorApplyReason(outcome.reason),actual=int(outcome.actual),limit=int(outcome.limit),changed=bool(outcome.changed),effective=self._copy_monitor_config(outcome.effective))
+	def monitor_snapshot(self)->MonitorSnapshot:
+		'Copy one bounded aggregate, histogram, and health snapshot.';value=native.MonitorSnapshot();_init(value,'coakka_http_host_monitor_snapshot_init')
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_monitor_snapshot(service,ctypes.byref(value)))
+		failure_count=int(value.failure_count);latency_count=int(value.latency_bucket_count)
+		if failure_count>native.MAX_MONITOR_FAILURES or latency_count>native.FIXED_LATENCY_BUCKETS:raise RuntimeError('native monitor snapshot exceeds its ABI bound')
+		return MonitorSnapshot(collecting=bool(value.collecting),stale=bool(value.stale),partial=bool(value.partial),snapshot_sequence=int(value.snapshot_sequence),observed_monotonic_ns=int(value.observed_monotonic_ns),collected_change_sequence=int(value.collected_change_sequence),admitted_requests=int(value.admitted_requests),request_bytes=int(value.request_bytes),exchange_completed=int(value.exchange_completed),exchange_failed=int(value.exchange_failed),exchange_timed_out=int(value.exchange_timed_out),exchange_disconnected=int(value.exchange_disconnected),exchange_cancelled=int(value.exchange_cancelled),response_status_family=(int(value.response_status_family[0]),int(value.response_status_family[1]),int(value.response_status_family[2]),int(value.response_status_family[3]),int(value.response_status_family[4])),retained_events=int(value.retained_events),overwritten_events=int(value.overwritten_events),dropped_events=int(value.dropped_events),signal_notifications=int(value.signal_notifications),coalesced_signals=int(value.coalesced_signals),signal_failures=int(value.signal_failures),config=self._copy_monitor_config(value.config),health=self._copy_health(value.health),failure_counts=tuple(MonitorFailureCount(int(value.failure_counts[i].reason),int(value.failure_counts[i].count))for i in range(failure_count)),latency_buckets=tuple(MonitorLatencyBucket(int(value.latency_buckets[i].upper_bound_ns),int(value.latency_buckets[i].count))for i in range(latency_count)))
+	def monitor_read(self,after_sequence:int,maximum_events:int)->MonitorEventPage:
+		'Copy a bounded page of operational events after one sequence.';maximum_events=_unsigned(maximum_events,32,'maximum_events')
+		if not 0<maximum_events<=native.FIXED_LATENCY_BUCKETS*4:raise ValueError('maximum_events is outside the native read bound')
+		events=(native.MonitorEvent*maximum_events)()
+		for item in events:_init(item,'coakka_http_host_monitor_event_init')
+		page=native.MonitorPage();_init(page,'coakka_http_host_monitor_page_init')
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_monitor_read(service,_unsigned(after_sequence,64,'after_sequence'),maximum_events,events,maximum_events,ctypes.byref(page)))
+		if page.count>maximum_events:raise RuntimeError('native monitor page exceeds its supplied capacity')
+		copied=tuple(MonitorEvent(kind=MonitorEventKind(item.kind),sequence=int(item.sequence),change_sequence=int(item.change_sequence),config_generation=int(item.config_generation),collection_epoch=int(item.collection_epoch),observed_monotonic_ns=int(item.observed_monotonic_ns),category=MonitorCategory(item.category),failure_reason=int(item.failure_reason),queue_scope=int(item.queue_scope),queue_depth=int(item.queue_depth),queue_capacity=int(item.queue_capacity),exchange=ExchangeId(int(item.exchange.slot),int(item.exchange.generation)))for item in events[:page.count]);return MonitorEventPage(events=copied,oldest_available_sequence=int(page.oldest_sequence),latest_sequence=int(page.latest_sequence),overwritten_events=int(page.overwritten_events),remaining_events=int(page.remaining_events))
+	def monitor_wait(self,timeout_ms:int)->bool:
+		'Wait for a coalesced monitor signal; return false on timeout.'
+		with self._monitor_waiter,self._borrow()as service:status=native.LIBRARY.library.coakka_http_host_monitor_wait(service,_timeout(timeout_ms))
+		if status==native.STATUS_TIMEOUT:return False
+		native.LIBRARY.check(status);return True
+	def monitor_interrupt(self)->None:
+		'Wake the sole monitor waiter without changing HTTP work.'
+		with self._borrow()as service:native.LIBRARY.check(native.LIBRARY.library.coakka_http_host_monitor_interrupt(service))