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.

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

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 Adapter Circuit APIs. For those chapters, use Builder and Data Contracts and Adapter Circuit.

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_pack_inspect_ex(...)	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_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

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(...)	read delayed-history contribution	vector length Nq	Step Execution
tdse_step_ir(...)	read independent-response contribution	vector length Nq	Step Execution
tdse_step_commit(...)	advance committed history	none	Step Execution
tdse_step_dr(...)	read committed direct response	vector length Nq	Step Execution

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_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_set_log_callback(...)	register a structured log sink	global setting
tdse_ext_set_log_level(...) / tdse_ext_get_log_level(...)	set or inspect log threshold	global setting
tdse_ext_log_emit(...)	emit a structured log record	integration helper
tdse_ext_set_deterministic_mode(...) / tdse_ext_get_deterministic_mode(...)	control reproducibility mode	global setting
tdse_ext_set_runtime_guard_config(...) / tdse_ext_get_runtime_guard_config(...)	control runtime guard behavior	warnings only; no numerical change
tdse_ext_get_runtime_guard_metrics(...) / tdse_ext_reset_runtime_guard_metrics(...)	inspect or clear guard metrics	metrics snapshot helpers
tdse_ext_update_runtime_guard_metrics(...)	update guard metrics	public for completeness, mainly runtime-internal
tdse_ext_status_from_runtime(...) / tdse_ext_status_from_builder(...) / tdse_ext_status_from_circuit_ac(...)	normalize module-local status codes	status mapping helpers
tdse_ext_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::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() / statusFromRuntime(...) / statusFromBuilder(...) / statusFromCircuitAc(...)	status mapping 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(...)
compute trial output terms	tdse_step_begin/op/hr/ir
advance committed state	tdse_step_commit(...)
inspect committed direct response	tdse_step_dr(...)
choose backend before stepping	tdse_backend_set(...) or tdse_backend_apply_plan(...)
inspect available backend capabilities	tdse_backend_registry_count/get
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