Decision record · ADR
ADR-0013: Materialize integration-rendered launch files in the control plane
Status: accepted | Date: 2026-07-12
References: RFC-0002, RFC-0003, RFC-0006, RFC-0007
Context
Section titled “Context”Some framework processes require effective launch configuration in a file even when that configuration contains control-plane-allocated endpoints. TensorRT-LLM prefill/decode workers require cache-transceiver configuration files, and its native disaggregated server requires a file containing the resolved context and generation targets.
Problem Statement
Section titled “Problem Statement”The integration is the authority for framework-specific configuration text, while the Rust control plane owns endpoint allocation, workspace-file access, target-machine effects, process lifecycle, dry-run, and records. The original adapter protocol returned only arguments and environment variables, so it could not carry a file that depends on final allocations without either hiding file creation inside a framework launcher or requiring a workspace-authored file that cannot contain dynamically allocated endpoints.
TensorRT-LLM adds a second composition boundary: its generated worker file must preserve non-owned fields from an operator-authored YAML file. A process-backed adapter can reopen that path from the workspace, but built-image and external-image adapters run inside the serving image and do not see the workspace. Mounting the whole workspace would make a narrow configuration read expose unrelated local content to the image.
Constraints
Section titled “Constraints”RFC-0006:C-INTEGRATIONS prohibits integrations from owning long-running lifecycle or authoritative record writes. RFC-0003:C-RUNTIME-WORKFLOWS requires local, SSH, and containerized launches to share lifecycle and evidence semantics. RFC-0002 already assigns each process a machine-local runtime-cache namespace, and RFC-0007 keeps runtime-local values out of portable image artifacts. RFC-0006:C-LAUNCH-FILES assigns declared source-file access to the control plane. The solution must preserve exact effective file contents in dry-run and records without making the integration perform target-machine writes or granting an image a broader workspace view.
Options Considered
Section titled “Options Considered”The viable options are protocol-declared source text plus protocol-declared launch files, an integration-owned launcher or memfd shim, workspace-authored static files, framework-specific control-plane construction, broad image mounts, host-only filesystem reads, or a second execution-scoped runtime-input root.
Decision
Section titled “Decision”We will extend the versioned integration boundary so an integration can declare the exact workspace text it needs for final rendering and rendered processes can declare immutable text launch inputs, while the Rust control plane supplies the declared source text and materializes the rendered inputs on the launch machine.
- One framework authority: the integration owns framework-specific composition after receiving concrete allocations and only the operator source text it declared.
- One file-access and effect authority: the control plane owns source-file reads, validated target-machine materialization, spawn ordering, failure handling, dry-run, and evidence.
- Realization-independent rendering: process-backed, built-image-backed, and external-image-backed adapters receive the same declared source content without a workspace mount.
- Concurrent correctness: content-derived output paths combined with atomic publication and verification of an existing same-digest file prevent cross-execution replacement or partial observation.
Implementation Notes
Section titled “Implementation Notes”The mechanism is limited to declared UTF-8 source text and immutable text launch inputs governed by RFC-0006:C-LAUNCH-FILES. It reuses the allocated runtime-cache root because that path is available during integration rendering and already has consistent local, SSH, and container projection. It does not introduce a general artifact graph, mutable shared volume protocol, arbitrary workspace reader or writer, directory mount, or portable image-content mechanism.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- File-only framework settings become first-class effective values in dry-run and execution records.
- Dynamic endpoint configuration works without copying adapter source into workspaces or adding a framework launcher process.
- Operator-authored framework settings can be composed identically across process-backed, built-image-backed, and external-image-backed lowering.
- An image receives only the source text selected by the integration rather than a workspace or directory mount.
- Local, SSH, and image-backed launches retain one lifecycle and evidence boundary.
- Framework-specific file syntax stays out of the Rust control plane.
Negative
Section titled “Negative”- The integration protocol and generated language models must change in lockstep.
- Declared source text increases adapter request size and becomes visible to the selected adapter realization; the mitigation is to send only exact declared files rather than surrounding directories.
- An unreadable or non-UTF-8 declared source becomes a resolution failure; the mitigation is an attributable path-specific error before launch.
- Materialization adds a pre-spawn failure class on local and remote machines; no runtime handle exists when publication fails.
- Digest-addressed runtime inputs persist in the machine-local cache. Dynamic settings may create additional small files and retain local endpoints or paths for the cache’s lifetime, under the same operator-controlled local-data posture as execution records.
- Incorrect path or publication handling could expose mismatched or partial content. Source digests, path confinement, output digest verification, existing-file verification, and atomic publication bound that risk.
Neutral
Section titled “Neutral”- Workspace-authored static files remain available when no composition or resolved value must be injected.
- Identical rendered content can reuse one immutable cache entry across executions.
- The effective rendered output, rather than the pre-merge source file alone, remains the launch configuration evidence.
Alternatives Considered
Section titled “Alternatives Considered”Declare immutable launch files in the adapter protocol and materialize them in the control plane (accepted)
Section titled “Declare immutable launch files in the adapter protocol and materialize them in the control plane (accepted)”- Pros: Preserves integration ownership of framework text and control-plane ownership of target-machine effects, Makes exact contents visible in dry-run and records across local, SSH, and container launches, Carries only integration-declared operator source text into final rendering, independent of adapter realization
- Cons: Requires a protocol version change and cross-runtime materialization support
Use an integration-owned launcher or memfd shim that writes configuration before exec (rejected)
Section titled “Use an integration-owned launcher or memfd shim that writes configuration before exec (rejected)”- Pros: Avoids changing the adapter protocol
- Cons: Hides a startup program and effective file lifecycle inside rendered argv or environment state, Expands runtime adapter-package requirements for external images and depends on file-descriptor behavior not guaranteed by the framework CLI
- Rejected because: It moves target-machine materialization and failure semantics into the integration boundary while providing weaker dry-run and record evidence.
Require workspace-authored static framework configuration files (rejected)
Section titled “Require workspace-authored static framework configuration files (rejected)”- Pros: Needs no protocol or runtime change for worker-only static settings
- Cons: Cannot encode control-plane-allocated router targets, Allows a file to contradict the resolved KV-transfer selection and creates a second authority for effective settings
- Rejected because: The concrete native router workflow requires configuration derived from final endpoint allocations.
Teach the Rust control plane to construct TensorRT-LLM configuration files directly (rejected)
Section titled “Teach the Rust control plane to construct TensorRT-LLM configuration files directly (rejected)”- Pros: Keeps target-machine writes in the control plane
- Cons: Moves framework-specific keys and command drift into the framework-neutral layer
- Rejected because: It violates the existing framework integration ownership boundary without removing the need for a generic file lifecycle.
Allocate an execution-scoped runtime-input root and late-bind file references after record creation (rejected)
Section titled “Allocate an execution-scoped runtime-input root and late-bind file references after record creation (rejected)”- Pros: Avoids persistent cache accumulation and naturally isolates concurrent executions
- Cons: Introduces a second runtime path projection and a late argument-substitution mechanism across local, SSH, and container launches, The final path is unavailable during integration rendering unless the protocol adds reference placeholders
- Rejected because: The existing runtime-cache root is already supplied during rendering and projected at the same path across launch modes; digest-bearing immutable files can safely reuse that boundary with less machinery.
Mount the workspace or the configuration’s containing directory into each image-backed adapter container (rejected)
Section titled “Mount the workspace or the configuration’s containing directory into each image-backed adapter container (rejected)”- Pros: Lets the integration keep reopening operator paths without another protocol field
- Cons: Exposes unrelated workspace content to a third-party serving image, Makes rendering depend on host/container path projection
- Rejected because: The adapter needs one declared text input, not authority to inspect the surrounding workspace.
Keep filesystem reads inside the integration and treat image-backed composition as unsupported (rejected)
Section titled “Keep filesystem reads inside the integration and treat image-backed composition as unsupported (rejected)”- Pros: Requires no additional protocol input
- Cons: Makes identical recipes lower differently by adapter realization, Contradicts the selected image-backed launch capability
- Rejected because: Host-only success would leave a real supported launch mode broken.