Resolved embedding safe band is not bound through composition, LM Studio readiness, and typed overflow handling

Context

Neo's resolved embedding safe-processing band is AiConfig.localModels.embedding.safeProcessingLimitTokens (default 28,672 tokens). The canonical llama.cpp lane allocates 32,768 tokens per slot, while LM Studio exposes the resident model's loaded context through strict lms ps metadata.

Source correction

The original ticket premise treated a client-supplied truncate: false field or per-request /slots polling as the missing safety witness. The pinned llama.cpp source establishes a different contract:

• handle_embeddings_impl() does not parse truncate.
• The server refuses an embedding that crosses the slot context, releases the task, and returns instead of computing a prefix-vector.
• The refusal carries n_prompt_tokens and n_ctx; the pinned server maps it to HTTP 400 with type exceed_context_size_error.
• A live canonical-profile receipt proved that /slots can starve during full embedding grind and must not be treated as an always-available per-request authority (#17024 receipt, Arm 3 and prescription 4).

The safe design therefore binds the resolved band at composition/readiness, classifies exact transport evidence, and leaves live provider-shape verification to its existing boot-time owner rather than adding a recurring request-path probe.

Problem

Four authority gaps remain:

1. Provider-lane composition and election compare an envelope with itself but do not carry the resolved environment-backed safe band as a versioned deployment input.
2. The production LM Studio postSpawn path verifies residency but does not apply the embedding safe-band floor to its already-fetched strict metadata.
3. LM Studio request preflight collapses a lane/configuration mismatch and a current input whose estimate exceeds trusted resident context into one untyped error, although they have different retry semantics.
4. The pinned llama.cpp structured overflow refusal reaches Knowledge Base ingestion as an unclassified HTTP error.

Without those distinctions, deployment drift can pass static validation, readiness can report green for an undersized LM Studio resident, and durable tenant-sync state cannot tell a repairable context mismatch from a current input that the provider positively refused as too large.

Intended Solution

• Make localModels.embedding.safeProcessingLimitTokens a positive-integer config leaf.
• Add the resolved band to provider-lane composition receipts and candidate deployment inputs; bump composition, election-plan, and election-report schemas to v2. The executable entrypoint reads AiConfig; pure analyzers receive the value by injection.
• Make LM Studio postSpawn run metadata-only embedding readiness from the strict resident rows already fetched by ensureLmsModelsLoaded. This path performs no embedding inference or tokenizer/model-file work.
• Split LM Studio request failures:
  • resident context below the configured requirement or safe band becomes EMBEDDING_CONTEXT_INSUFFICIENT, mapped to KB_VECTOR_EMBED_CONTEXT_INSUFFICIENT with deferrable disposition;
  • a current input estimate above the trusted resident context becomes EMBEDDING_INPUT_TRUNCATED, mapped to KB_VECTOR_EMBED_INPUT_TRUNCATED with rejected disposition.
  • when both conditions are visible, resident-policy insufficiency wins until the resident is repaired; only a policy-compliant resident can authorize the estimate-based permanent-input classification.
• Translate only the pinned llama.cpp structured HTTP 400 exceed_context_size_error receipt, with valid positive n_prompt_tokens and n_ctx, into EMBEDDING_INPUT_TRUNCATED. Do not infer permanence from response prose.
• Preserve the legacy request body for generic OpenAI-compatible endpoints. Do not send truncate, add a strict-slot capability leaf, or poll /slots per embedding request.

Acceptance Criteria

• Invalid embedding safe-band environment values cannot become an invalid resolved leaf; the default remains 28,672.
• Composition fails when the declared per-slot context is below the resolved safe band and names both numbers. A non-default safe-band environment value is proven through the real CLI entrypoint.
• Provider-lane composition receipts, election plans, and election reports use v2 schemas and carry the safe band as one canonical deployment input. All candidates must share the same value, and application environment drift is rejected.
• The production ConfiguredTaskDefinitionsService -> lms.postSpawn -> ensureLmsModelsLoaded path applies metadata-only embedding readiness when LM Studio owns the embedding role. A known undersized resident is not ready, and zero embedding canaries are issued.
• LM Studio context-policy insufficiency throws EMBEDDING_CONTEXT_INSUFFICIENT before POST and reaches Knowledge Base classification as KB_VECTOR_EMBED_CONTEXT_INSUFFICIENT with deferrable disposition.
• A current LM Studio input estimate above the trusted resident context throws EMBEDDING_INPUT_TRUNCATED before POST and reaches KB_VECTOR_EMBED_INPUT_TRUNCATED with rejected disposition.
• The exact pinned llama.cpp structured overflow receipt maps to EMBEDDING_INPUT_TRUNCATED; malformed, partial, prose-only, or foreign 400 responses retain existing unclassified/deferrable behavior.
• Generic OpenAI-compatible requests preserve their existing {model, input} body and perform zero /slots calls.
• No request-path /slots capability, cache, probe, or recurring model work is introduced by this ticket.

Contract Ledger

Scope Transfer

[SCOPE_TRANSFERRED] Live llama.cpp shape-versus-envelope verification belongs to #17069. That ticket already owns the boot-time /slots observation, comparison with the elected envelope, health degradation, and deployment-state projection. This ticket does not duplicate that heavy cross-service work at the request boundary.

The transfer is evidence-driven: the pinned server already refuses an oversized embedding structurally, while the live #17024 receipt proves /slots can be unavailable exactly when all slots are doing useful work. A per-request probe would turn expected saturation into false failures and recurring zero-progress diagnostics.

Out of Scope

• Boot/runtime lane-shape comparison and deployment-state projection (#17069).
• Changing chunking or the 28,672-token default band.
• Auditing or re-embedding historical corpus rows.
• Claiming arbitrary OpenAI-compatible providers are truncation-safe without trusted metadata or an exact structured refusal contract.
• Admission ordering, activity-ledger expiry, or actuator deadlines.

Avoided Traps

• truncate: false as safety: the pinned handler ignores it.
• Per-request /slots as safety: measured starvation under load makes it unsuitable as recurring transport authority.
• Provider prose as proof: only the exact structured pinned refusal is classified as permanent.
• Conflating policy mismatch with current-input overflow: the former is deferrable; the latter is rejected.
• Static default as deployment truth: executable consumers read the resolved leaf; pure helpers receive it by injection.
• Failing generic endpoints closed: compatibility behavior remains unchanged outside the declared local authorities.

Decision Record Impact

No new ADR. The implementation follows ADR-0019: resolved config is read at production/executable use sites, analyzers remain injected and pure, and no second environment authority is created. The v2 schema bumps are required because the signed composition/election artifact shape gains one deployment input.

Related

Parent epic: #17072
Related: #17069
Related: #17024
Related: #16853