[stikves]

Summary

Replaces the InferenceOptions.includeLogits: Bool flag with two request axes shared by all four engines (sequential, pipelined, static/ANE, VLM):

• tokens: TokenRequest (.none / .sample): whether the engine samples and returns a token.
• logits: LogitsRequest (.none / .lastPosition / .allPositions): which positions' logits it returns.

Presets cover the common pairs:

Preset	tokens	logits	Use
.prefill	.none	.none	prefill and warmup chunks
.extend (alias .default)	.sample	.none	decode
.eval	.none	.allPositions	perplexity and scoring
.guided	.none	.lastPosition	constrained decoding
.sampleWithLogits	.sample	.lastPosition	decode and keep the last-row logits

Motivation

One boolean had to answer two separate questions: whether to sample a token, and which logits to return.

• The pipelined engine samples on the GPU and never copies logits to the CPU, so it can only return a token.
• Perplexity and evaluation need logits at every position; constrained decoding needs only the last row.
• Logit inspection and scoring want a token and its logits together.

With an action axis and an output axis, a caller asks for exactly what it needs, and an engine can reject a request it can't serve before running a forward pass.

Scope

This PR changes the request API and migrates every call site. Engine behavior is unchanged:

• Engines read only returnsLogits (logits != .none). They still sample when tokens is .none, and return one [vocabSize] row per step for both .lastPosition and .allPositions. The doc comments on TokenRequest and LogitsRequest say so.
• The pipelined engine still rejects any request that returns logits.

Compatibility

Source-compatible. The default (tokens: .sample, logits: .none) matches the old includeLogits: false, so decode is unchanged. init(includeLogits:) and the includeLogits property stay as deprecated shims: true maps to logits: .lastPosition, false to logits: .none, with tokens: .sample.

Verification

• On the current head (merged with main at cc3c234), the package and tests build, and 94 tests pass across the InferenceOptions, generate(), BatchScheduler, cancel, stop-reason, idempotent-engine and pipelined-constrained suites. These include tests for every preset, returnsLogits, and both deprecated shims.
• Before that merge, greedy decode was byte-identical to the base commit on a 135M fp16 model and a 0.8B hybrid model, on both the sequential and pipelined engines, and the pipelined engine's rejection of logit-returning requests matched the base binary. The merge changed one call site (CompletionHandler.scoreOnEngine, now .eval); the golden check was not re-run after it.

Follow-ups

Left for separate changes:

• Skip the CPU logits readback for .none and narrow it to the last row for .lastPosition on the sequential and VLM engines.
• Skip sampling when tokens is .none. InferenceOutput.tokenId is non-optional today, so this also needs an output-side change.
• Support .allPositions on the static and pipelined engines.
• Engine consolidation and warmup work built on these options.

[carinapeng]

Please address rest of comments, otherwise thanks for the changes from prev review :)