Runtime Integration

Use this chapter as the Runtime lookup page when the real question is not "how does the step loop work?" but "which API family should I reach for first?" It is intentionally compact: a map into the Runtime APIs, not a replacement for the generated API Reference or the deeper lifecycle chapters.

Read this chapter first when you already know TDSE belongs in your host loop but do not yet know whether the next stop should be Builder, lifecycle, step execution, or the generated API reference.

Related Chapters

• For lifecycle rules, see Runtime Lifecycle.
• For trial and commit semantics, see Step Execution.
• For Builder APIs, see Builder and Data Contracts.
• For backend support levels, see Runtime Backend Support Matrix.
• For entitlement setup and failure handling, see Product Authorization.
• For operational triage, see Runtime Troubleshooting Runbook.
• For tuning knobs, see Runtime Performance Tuning.

How This Runtime Part Is Split

The Runtime material stays split into short sections on purpose. Most customer teams do not read Runtime linearly; they jump to the contract surface that matches the host question in front of them.

If your question is...	Read this chapter first
which API family do I need	this chapter
who owns the handle and how do I shut it down	Runtime Lifecycle
what exact calls happen every accepted step	Step Execution
what happens under overlap, races, or teardown contention	Concurrency and Shutdown
how many models, threads, or GPU shares can I afford	Threading and Scaling and Multi-Model Patterns
which backend is production-supported	Runtime Backend Support Matrix
what do I collect when Runtime fails	Runtime Troubleshooting Runbook
how do I tune backend knobs	Runtime Performance Tuning

Scope Boundary

This chapter covers Runtime APIs only:

• core model lifecycle
• runtime snapshots and diagnostics
• trial/commit step execution
• runtime-facing perf / ext controls that operate on tdse_model_t*
• C++ wrappers for the same runtime-facing surface

It does not list Builder or Circuit SDK APIs. For those chapters, use Builder and Data Contracts and Circuit SDK.

Core Runtime Lifecycle APIs

API	First Job	Use It When	Details Live In
tdse_model_create(...)	create a runtime handle from pack bytes	every normal create path	Runtime Lifecycle
tdse_model_close(...)	request a close without waiting for teardown	you need an immediate lifecycle answer	Runtime Lifecycle
tdse_model_destroy(...)	shut down with an explicit wait policy	normal host-managed shutdown	Runtime Lifecycle
tdse_model_release(...)	perform terminal cleanup in finalizer-style paths	destructor, guard, or finally cleanup	Runtime Lifecycle
tdse_model_reset(...)	clear committed state before intentional reuse	you are reusing a live handle on purpose	Runtime Lifecycle

Runtime Version And Introspection APIs

API	First Job	What It Returns	Notes
tdse_version_string(...)	get full version text	full semantic version string	stable runtime version text
tdse_version_major(...)	get major version	semantic version major component	integer component
tdse_version_minor(...)	get minor version	semantic version minor component	integer component
tdse_version_patch(...)	get patch version	semantic version patch component	integer component
tdse_pack_inspect(...)	inspect pack dimensions before create	tdse_model_info_t decoded from pack bytes	no runtime handle allocation
tdse_runtime_pack_inspect_summary(...)	inspect pack metadata before create	tdse_pack_summary_t with pack version and payload summary	metadata-only path

Runtime Snapshot And Diagnostics APIs

API	First Job	What It Returns	Notes
tdse_model_info(...)	read static model metadata	model dimensions and fixed properties	out_info->struct_size must be set
tdse_model_state_info(...)	read live execution state	current runtime state	out_state->struct_size must be set
tdse_model_last_error_info(...)	read the last failure snapshot	most recent non-OK runtime result on the handle	sticky until next failure or tdse_model_reset(...)
tdse_model_diagnostics_summary(...)	read the stable compact support snapshot	model info, current state, sticky last error, health, and compute-type summary	preferred first-response Runtime diagnostic record
tdse_model_diagnostics_payload(...)	read one optional diagnostic domain	one caller-initialized versioned CPU-route, numeric, memory, accelerator, CPU-execution, CPU-precision, or partition payload	request only the detail domain the caller consumes
tdse_model_diagnostics_query_many(...)	read a consistent diagnostic bundle	one summary plus multiple caller-owned versioned payloads	preferred when all outputs must represent one internal snapshot
tdse_model_health_info(...)	read the current health snapshot	initialized tdse_model_health_info_t	operational health without collecting the full diagnostic bundle
tdse_model_history_prefetch_info(...)	inspect history-prefetch state	initialized tdse_model_history_prefetch_info_t	real-time latency and fallback triage
tdse_model_partition_diagnostics_json(...)	export partition diagnostics	caller-sized JSON buffer	use a NULL/zero sizing call first
tdse_pack_error_token(...)	decode create-time pack errors	readable token for a pack-error code	uses tdse_model_create_diagnostics_t::pack_error_code
tdse_status_message(...)	decode runtime status codes	readable text for a runtime status code	status text only
tdse_status_error_category_v2(...) / tdse_status_stable_reason_v2(...)	classify failures for automation	stable category and reason tokens	prefer the v2 classifiers in new integrations

Step Execution APIs

Use this table to find the right step API quickly. For the full trial/commit model, sequencing rules, and caller buffer contracts, switch to Step Execution.

API	First Job	Typical Output	Details Live In
tdse_step_begin(...)	start or re-enter a trial step	none	Step Execution
tdse_step_op(...)	read the instantaneous operator	dense block Np x Np or Nq x Np	Step Execution
tdse_step_hr_v2(...)	read delayed-history contribution with capacity checking	vector length Nq; required count is always reported	Step Execution
tdse_step_ir_v2(...)	read independent-response contribution with capacity checking	vector length Nq; required count is always reported	Step Execution
tdse_step_commit_v2(...)	advance committed history with an explicit Np count	none	Step Execution
tdse_step_dr_v2(...)	read committed direct response with capacity checking	vector length Nq; required count is always reported	Step Execution

The unsuffixed tdse_step_hr, tdse_step_ir, tdse_step_commit, and tdse_step_dr functions remain ABI-compatible entry points, but they cannot validate caller buffer capacity. New C integrations and language bindings should use the _v2 functions.

Execution Policy And Resource APIs

Runtime separates a requested execution policy from the concrete resources available to a model:

API family	First job	Notes
tdse_execution_policy_init(...)	initialize policy defaults	set policy before the first successful tdse_step_begin(...)
tdse_execution_resource_set_init(...) and resource helpers	describe CPU, GPU, FPGA, or remote-GPU resources	resource discovery does not imply entitlement or qualification
tdse_model_set_execution_policy(...) / tdse_model_get_execution_policy(...)	set or inspect a model policy	pre-step configuration
tdse_model_set_execution_resources(...) / tdse_model_get_execution_resources(...)	bind or inspect resources	GPU and FPGA binding invokes the corresponding Add-on authorization
tdse_model_clear_execution_resources(...)	return to policy-driven selection	pre-step configuration

Use Backend Selection and Performance for availability and qualification. Use Product Authorization for entitlement combinations.

Runtime-Facing Perf And Ext APIs

perf APIs

API	First Job	Notes
tdse_backend_registry_count(...) / tdse_backend_registry_get(...)	enumerate available backends	capability discovery
tdse_backend_set(...)	choose a backend before stepping	pre-step only
tdse_backend_get_active(...)	inspect the active backend	reads last effective backend on the model
tdse_backend_apply_plan(...)	apply a JSON backend plan	pre-step only
tdse_backend_qualification_query(...)	query qualification evidence for one backend	capability, authorization, and qualification are separate facts
tdse_cuda_backend_set_config(...) / tdse_cuda_backend_get_config(...)	set or inspect CUDA options	setter is pre-step only
tdse_compute_precision_set(...) / tdse_compute_precision_get(...)	set or inspect CPU history precision	setter is pre-step only
tdse_local_threads_set(...) / tdse_local_threads_get(...)	set or inspect local CPU thread override	setter is pre-step only
tdse_backend_id_name(...) / tdse_backend_id_from_name(...)	map backend ids and names	token lookup helpers
tdse_perf_get_build_features_json(...)	export build/runtime feature flags	pass out_json = NULL to query required bytes

ext APIs

API	First Job	Notes
tdse_ext_context_create(...) / tdse_ext_context_destroy(...)	own extension state explicitly	keep alive while borrowed by models
tdse_ext_context_set_log_callback(...)	register a structured log sink	context-local setting
tdse_ext_context_set_log_level(...) / tdse_ext_context_get_log_level(...)	set or inspect log threshold	context-local setting
tdse_ext_context_log_emit(...)	emit a structured log record	integration helper
tdse_ext_context_set_deterministic_mode(...) / tdse_ext_context_get_deterministic_mode(...)	control reproducibility mode	context-local setting
tdse_ext_context_set_runtime_guard_config_v2(...) / tdse_ext_context_get_runtime_guard_config(...)	validate, set, or inspect runtime guard behavior	warnings only; no numerical change
tdse_ext_context_get_runtime_guard_metrics(...) / tdse_ext_context_reset_runtime_guard_metrics(...)	inspect or clear guard metrics	metrics snapshot helpers
tdse_status_message(...) / tdse_ext_pack_error_name(...)	decode unified status and pack errors	readable token helpers

C++ Wrapper Equivalents

C++ API	Runtime Surface	Notes
tdse::Model::fromMemory(...)	tdse_model_create(...)	request-scoped create diagnostics overload available
tdse::Model::empty() / operator bool()	wrapper state only	use after move, close, destroy, or release to gate business calls
tdse::Model::info()	tdse_model_info(...)	returns tdse_model_info_t
tdse::Model::stateInfo()	tdse_model_state_info(...)	returns tdse_model_state_info_t
tdse::Model::lastErrorInfo()	tdse_model_last_error_info(...)	sticky failure snapshot
tdse::Model::diagnosticsSummary() / tryDiagnosticsSummary()	tdse_model_diagnostics_summary(...)	stable compact Runtime support snapshot
tdse::Model::diagnosticsPayload() / tryDiagnosticsPayload()	tdse_model_diagnostics_payload(...)	one caller-selected versioned detail payload
tdse::Model::diagnosticsQueryMany() / tryDiagnosticsQueryMany()	tdse_model_diagnostics_query_many(...)	one consistent summary plus payload set
tdse::Model::destroy(options)	tdse_model_destroy(...)	canonical bounded destroy
tdse::Model::release()	tdse_model_release(...)	finalizer cleanup
tdse::Model::beginStep() / stepOp() / stepHr() / stepIr() / commit() / stepDr()	runtime step APIs	stepOp() defaults to Np x Np; full=true selects Nq x Np; wrapper enforces Np / Nq buffer sizes
tdse::perf::backendCount() / backendGet()	backend registry APIs	C++ registry enumeration
tdse::perf::setBackend() / activeBackend() / applyPlan()	backend routing APIs	runtime-facing perf control
tdse::perf::setCudaConfig() / getCudaConfig()	CUDA config APIs	per-model CUDA options
tdse::perf::setComputePrecision() / getComputePrecision()	precision APIs	CPU history precision
tdse::perf::setLocalThreads() / getLocalThreads()	local thread APIs	local CPU thread override
tdse::perf::getBuildFeaturesJson(...)	tdse_perf_get_build_features_json(...)	returns JSON through std::string
tdse::ext::setLogCallback() / setLogLevel() / logLevel()	ext logging APIs	logging wrapper coverage
tdse::ext::setDeterministicMode() / deterministicMode()	deterministic-mode APIs	global runtime toggle
tdse::ext::setRuntimeGuardConfig() / runtimeGuardConfig() / runtimeGuardMetrics() / resetRuntimeGuardMetrics()	runtime guard APIs	stable-guard wrapper coverage
tdse::ext::statusMessage() / packErrorName()	status helper APIs	readable status and token helpers

Recommended Usage Map

Situation	Recommended API
create a model	tdse_model_create(...)
check runtime version	tdse_version_string(...)
inspect static shape	tdse_model_info(...)
inspect live state	tdse_model_state_info(...)
inspect last runtime failure	tdse_model_last_error_info(...)
collect first-response runtime diagnostics	tdse_model_diagnostics_summary(...); use tdse_model_diagnostics_query_many(...) when detail payloads must share the same snapshot
compute trial output terms	tdse_step_begin(...), tdse_step_op(...), tdse_step_hr_v2(...), tdse_step_ir_v2(...)
advance committed state	tdse_step_commit_v2(...)
inspect committed direct response	tdse_step_dr_v2(...)
bind CPU, GPU, FPGA, or remote resources	tdse_model_set_execution_resources(...)
evaluate or integrate product entitlements	Product Authorization
choose backend before stepping	tdse_backend_set(...) or tdse_backend_apply_plan(...)
inspect available backend capabilities	tdse_backend_registry_count/get
decide if a backend is production-supported	Runtime Backend Support Matrix
collect an incident bundle	Runtime Troubleshooting Runbook
tune AUTO, CPU, CUDA, or FPGA knobs	Runtime Performance Tuning
query build/runtime feature flags	tdse_perf_get_build_features_json(...)
normal host shutdown	tdse_model_destroy(...)
terminal cleanup path	tdse_model_release(...)

Quick Memory Aid

If you remember only three runtime ideas, remember these:

1. create is request-scoped and diagnostic-rich
2. commit is the only state-advancing step call
3. perf setters are pre-step only; after the first successful begin, configuration is frozen