Problem
Tool response payloads include a mix of fields that are part of the stable contract (e.g., matches, total_count, namespace) and fields that are experimental or may change before 1.0 (e.g., decision_trace, degraded, degradation_reason, hybrid_leg_failed, rerank_skipped_reason). There is no explicit annotation, naming convention, or structural separation distinguishing stable fields from experimental ones. Consumers (both LLM agents and programmatic integrators) cannot know which fields are safe to depend on across minor version bumps. The deprecation policy document (PR #122) establishes a breaking-change process but does not define which current fields are in the stable set vs. the experimental set.
Acceptance Criteria
Implementation Notes
The simplest approach is a nested experimental key in response objects: { namespace, matches, total_count, experimental: { decision_trace, degraded, ... } }. This is a breaking change to response shape — coordinate with the deprecation policy. An alternative non-breaking approach: add @experimental JSDoc annotations to fields in src/types.ts and document in TOOLS.md which fields are experimental, deferring the structural separation to v1.0. Given pre-1.0 status, the structural approach is preferred (consumers expect breaking changes). Update HybridQueryResult in src/types.ts and any response builder utilities. The format-query-result helper (item 1) is the code that constructs these responses — coordinate timing.
References
- Eval finding: Test 34 (API Stability Discipline) — survived; cluster "stable-experimental-field-boundary"
- Related files:
src/types.ts, docs/TOOLS.md, src/core/server/tool-response.ts, docs/MIGRATION.md (deprecation policy)
Problem
Tool response payloads include a mix of fields that are part of the stable contract (e.g.,
matches,total_count,namespace) and fields that are experimental or may change before 1.0 (e.g.,decision_trace,degraded,degradation_reason,hybrid_leg_failed,rerank_skipped_reason). There is no explicit annotation, naming convention, or structural separation distinguishing stable fields from experimental ones. Consumers (both LLM agents and programmatic integrators) cannot know which fields are safe to depend on across minor version bumps. The deprecation policy document (PR #122) establishes a breaking-change process but does not define which current fields are in the stable set vs. the experimental set.Acceptance Criteria
src/types.tsclearly separates stable fields from experimental fields (via naming convention likeexperimental_*prefix, nestedexperimental: {}object, or JSDoc@experimentaltags)docs/TOOLS.mddocuments the stability classification for every response fieldImplementation Notes
The simplest approach is a nested
experimentalkey in response objects:{ namespace, matches, total_count, experimental: { decision_trace, degraded, ... } }. This is a breaking change to response shape — coordinate with the deprecation policy. An alternative non-breaking approach: add@experimentalJSDoc annotations to fields insrc/types.tsand document in TOOLS.md which fields are experimental, deferring the structural separation to v1.0. Given pre-1.0 status, the structural approach is preferred (consumers expect breaking changes). UpdateHybridQueryResultinsrc/types.tsand any response builder utilities. Theformat-query-resulthelper (item 1) is the code that constructs these responses — coordinate timing.References
src/types.ts,docs/TOOLS.md,src/core/server/tool-response.ts,docs/MIGRATION.md(deprecation policy)