feat: document GenerationConfig hint/guarantee rule + add EmbeddingBackend capabilities (#1834)

[roryford]

Small, additive, non-breaking polish addressing three deferred items from #1834. Source-only stability (no -enable-library-evolution), so all three are feat:, not feat!:.

Changes

Item #1 — GenerationConfig throw-vs-silent-ignore rule (doc). Added a type-level DocC block on GenerationConfig stating the rule once: capability-gated guarantees (e.g. grammar) MUST throw InferenceError.unsupportedGrammar rather than silently degrade; advisory hints (seed, minP, jsonMode, sampler penalties, vendor knobs) are best-effort and silently ignored by backends that don't support them. No field changed.

Item #15 — EmbeddingBackend capabilities (additive). New public EmbeddingCapabilities value type (Sendable/Codable/Equatable/Hashable) with maxBatchSize, maxInputLength, producesNormalizedVectors, a memberwise init with safe defaults, and EmbeddingCapabilities.default. Added var capabilities to the EmbeddingBackend protocol with a protocol-extension default (.default) — the same non-breaking pattern as InferenceBackend.manifest/secureWipe, so existing conformers don't break. Tightened the dimensions and embed(_:) contract docs (load-time meaning of dimensions; one-vector-per-input postcondition on embed).

Item #2 — vendor-knob cleanup note (docs-only). Added a plain // comment by the llama* sampler fields noting they're backend-specific knobs on the shared type, accepted as tech debt, with relocation deferred and tracked in #1834. Fields unchanged.

Non-breaking

All additive: new type + a protocol requirement satisfied by a protocol-extension default. No vendor field removed or relocated, no backendSpecific container added, no Package.swift/Package.resolved change. Source-only stability means this does not break ABI.

Why not more

The relocate+remove of the llama* vendor fields into the companion package was deliberately deferred — cross-repo blast radius. An adversarial review concluded these items are not freeze-blocking, so this PR ships the docs + the additive capabilities surface only.

Tests

Tests/ManifoldInferenceTests/EmbeddingBackendProtocolTests.swift:

• a conformer that does not override capabilities returns EmbeddingCapabilities.default (proves the non-breaking default);
• EmbeddingCapabilities Codable round-trips.

Scoped suite: swift test --filter EmbeddingBackendProtocolTests → 7/7 pass. Sabotage-verified the default test fails when the protocol-extension default is broken, then reverted.

🤖 Generated with Claude Code