Skip to content

Decision record · ADR

ADR-0048: Open an engine-worker settings escape hatch on the Specialized Engine contract

Status: accepted | Date: 2026-09-16

References: RFC-0003, RFC-0006

The Specialized Engine integration serves every Engine that implements the closed token-worker contract: one reusable package, a settings model holding the seven-field contract intersection, unknown fields rejected, and no settings escape hatch. The package deliberately contains no engine, architecture, or kernel branches, so the closed surface was originally a reasonable posture — a specialized engine’s knob surface was expected to be narrow, fully known, and common across implementations.

That premise no longer holds. Two new Engine implementations are under active development in their own repositories, and each carries implementation-specific command-line and environment knobs that do not belong in the shared contract: the Rust implementation takes a speculative-decoding mechanism and block size (--speculative dspark --speculative-block-size), and the C++ implementation takes a compiler prefill profile with its chunk parameter (--prefill-profile, --prefill-chunk) plus environment switches. These knobs are single-engine and fast-evolving; promoting each into the shared typed settings would couple the common integration to one engine’s internals and force an integration change and package release for every experimental knob.

The available paths today are both poor fits. First-class promotion has the coupling and release-friction problems above. The sanctioned alternative already observed in the C++ engine repository is a downstream maintained adapter extension — separately versioned, source-pinned, and tested through the managed integration — which is a heavy discipline for what is often passing one flag, and it slows exactly the implementation experiments the engines are built for.

No normative artifact forbids the hatch: RFC-0006:C-INTEGRATIONS already permits open framework parameters in an explicitly named settings escape hatch whose exact effective contents are returned and recorded, and RFC-0003:C-RESOLUTION already fixes the escape-hatch merge semantics the other four integrations use with an InferLab-owned-option blacklist. The Specialized Engine integration simply never opened one. The design question is how to admit engine-specific knobs during implementation bring-up without compromising the contract’s typed core or the integration’s engine-neutrality.

Add extra_args and extra_env settings to the Specialized Engine contract settings, scoped to the Engine worker process and aligned with the four framework integrations. The adapter SDK’s owned-option validation rejects InferLab-owned flags ahead of the -- verbatim sentinel, the shared merge helper composes operator arguments with the managed argv under RFC-0003:C-RESOLUTION, and the exact effective hatch contents are returned and recorded as RFC-0006:C-INTEGRATIONS requires. The owned-option blacklist covers the canonical command flags (--listen, --model, --served-model-name, --tensor-parallel-size) and every flag rendered from a typed setting, including the two per-rank prefix-cache flags rendered from prefix_cache_ranks.

The SMG Gateway process gets no hatch: its knob surface is fixed to the tokenspeed-smg implementation and owned by the plan. Typed settings remain the contract intersection; a knob that later proves stable and common across Engine implementations may be promoted through a contract revision, following the same typed-plus-hatch layering the framework integrations use. The hatch carries Engine command-line and environment knobs only — protocol-behavior extensions such as sampling forwarding or gateway stop semantics remain on the separately governed maintained-adapter path. The Engine contract’s typed surface and version are unchanged, because the hatch places no new obligation on Engine implementations: an Engine still accepts exactly the canonical command plus the typed settings it declares, and hatch arguments are its own implementation-defined extensions.

Positive: Engine bring-up and iteration proceed without an integration release or adapter fork per knob, and all five integrations now share one escape-hatch shape and merge semantics. Record comparability is preserved because the exact hatch contents return in effective settings and the rendered commands are recorded verbatim. The typed contract core, the plan-owned Gateway, and the integration’s engine-neutrality are untouched, and no RFC amendment is needed because RFC-0006:C-INTEGRATIONS already governs hatch behavior.

Negative: planning-time validation of hatch contents ends at the owned-option blacklist. A misspelled or semantically invalid engine flag fails at Engine startup rather than at planning, and InferLab cannot attest engine-specific knob semantics. Adopting the shared merge semantics also imports the deliberate-override path: tokens after the -- sentinel bypass the blacklist and are appended verbatim, so a determined operator can shadow even plan-derived managed flags — endpoint, model locator, device width — where engine last-wins parsing decides the outcome and the recorded verbatim command is the only attestation of the divergence; this is the RFC-sanctioned posture the framework integrations already carry, not a new exposure class. Qualification claims must be read together with the recorded hatch contents: a run exercised through the hatch demonstrates that exact configuration, not the typed contract alone.

Neutral: the contract documentation posture changes from fully closed to closed-core-plus-recorded-hatch. Whether a run used the hatch is visible in its record but is not separately flagged in the backend-support matrix, which continues to qualify declared configurations. Engine repositories keep their maintained-adapter discipline for the protocol-behavior surface the hatch does not cover.

Open an engine-worker extra_args/extra_env escape hatch aligned with the other four integrations (accepted)

Section titled “Open an engine-worker extra_args/extra_env escape hatch aligned with the other four integrations (accepted)”
  • Pros: Unblocks engine bring-up experiments without an integration release or adapter fork per knob, Hatch contents cross as recorded effective settings, preserving record comparability and auditability, Reuses the SDK-owned blacklist validation and RFC-0003:C-RESOLUTION merge semantics already proven by the four framework integrations
  • Cons: Planning-time validation stops at the owned-option blacklist; a misspelled or semantically wrong engine flag surfaces only at engine startup

Keep the contract closed and first-class each new engine knob into the shared typed settings (rejected)

Section titled “Keep the contract closed and first-class each new engine knob into the shared typed settings (rejected)”
  • Pros: Fully typed planning-time validation for every knob
  • Cons: Couples the common integration to single-engine internals, contradicting its no-engine-branches ownership, Every experimental knob requires an integration change and package release, stalling implementation attempts
  • Rejected because: The blocked knobs are single-engine and fast-evolving; the shared settings model is the contract intersection, not a per-engine knob registry.

Keep the contract closed and rely on downstream maintained adapter extensions (rejected)

Section titled “Keep the contract closed and rely on downstream maintained adapter extensions (rejected)”
  • Pros: Keeps the stock integration surface minimal and puts engine-specific spelling in engine-owned hands
  • Cons: Separate versioning, source pinning, and managed testing of a forked adapter is heavy discipline for passing one flag, and is already the observed bottleneck in the C++ engine repository
  • Rejected because: The fork path stays justified for protocol-behavior changes but is disproportionate for CLI knobs; it converts every experiment into adapter maintenance.

Constrain the hatch with an engine-flag allowlist (rejected)

Section titled “Constrain the hatch with an engine-flag allowlist (rejected)”
  • Pros: Retains planning-time control over admitted knobs
  • Cons: The allowlist lives in the integration, so each new knob still forces an integration change — the same friction with extra machinery
  • Rejected because: An allowlist re-introduces the release-per-knob bottleneck under a more complex mechanism; the recorded open hatch dominates it.