Arguments, settings and documented facts disagree or lack one checked source #570
Labels
No labels
code-review
correctness
dos
performance
security
severity/high
severity/low
severity/medium
tech-debt
Kind/Breaking
Kind/Bug
Kind/Documentation
Kind/Enhancement
Kind/Feature
Kind/Security
Kind/Testing
Priority
Critical
Priority
High
Priority
Low
Priority
Medium
Reviewed
Confirmed
Reviewed
Duplicate
Reviewed
Invalid
Reviewed
Won't Fix
Status
Abandoned
Status
Blocked
Status
Need More Info
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
h-dv/code-index#570
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Scope (consolidated 2026-11-12)
Clients encounter uneven filters, names and limits across tools. Operators also need settings, environment variables and CLI flags to share validation, defaults and precedence. Documentation must describe the shipped behavior and derive facts that otherwise drift. One registry should generate or check these contracts and expose the effective values and their sources.
Priority: Medium · Risk: cost · Size: L
Merged into this ticket: #527 (Documentation truth and structure)
Done
policy, validation and applied-range projection incrates/mcp-server/src/arguments.rsdrive schemas/errors;docs/mcp-arguments.mdis checked in both directions, and list/dependency/gap tools accept concise output.every_published_string_argument_has_a_safe_boundaryandtext_query_length_refusal_is_bounded_before_dispatchincrates/mcp-server/tests/argument_reference_e2e.rsgrade it. Release verification stays in #575.docs/configuration.mdinventories accepted keys/environment variables;configuration_reference_matches_decoder_both_waysincrates/indexer/tests/configuration_reference.rschecks key-table/decoder agreement.Remaining
Argument families and names
Settings registry and disclosure
Compatibility and release settings
Documentation structure and facts
Acceptance
Decisions needed from the operator
Suggested order
Original report
Follow-up to the configuration and argument audit of 2026-11-11 (operator principle: the system must be easy, consistent, fully documented and trustful for user, MCP client and agent). The audit's ten blockers are fixed in the v0.41.49 train. These six findings need one shared design, not six separate fixes.
S1 — Common arguments are accepted unevenly.
list_files,get_dependenciesandresolution_gapsrejectresponse_format, which row-producing siblings accept.resolution_gapscannot page its sample.list_files, the diff tools andrepo_maplacklang. Graph, dependency, outline and map tools cannot narrow output bypath_glob. Proposal: define capability families (row lists, graphs, single objects, budgeted output) and require each family's common arguments or a documented exemption.S2 — One concept has several names. Examples:
idle_timeout_min/idle-min;registry-url/catalog/source; CLIsha256/expect-digest/digestagainst MCPdigest;baseagainstdiff_base;id/symbol_id/target.response_formatmeans detailed/concise everywhere exceptread_code, where it means json/text. Proposal: record the canonical concept and scope in the registry, add compatible aliases where the cost is high, and separate output encoding from verbosity.S3 — Defaults, enums and bounds are not machine-readable everywhere. Page caps, batch caps, enum vocabularies and project defaults live in prose and handlers. The v0.41.49 train moved the numeric bounds it found into the schemas; the enums,
maxItemsand defaults are still open. Proposal: generate schema constraints, argument descriptions and the human reference from the same values.S4 — The same duration setting is validated differently. The daemon requires 10–60000 ms for debounce and falls back with a warning; the foreground watcher accepts any value. Reconcile minutes multiply without saturation, idle minutes saturate. Proposal: shared typed duration parsers with one zero/range rule.
S5 — Applied values are disclosed unevenly. Some invalid environment values warn, several numeric ones silently use the default.
search_textclampscontext_tokensto 1–64 without echoing the applied width, whilerepo_mapechoes its clamped budget. Proposal: one requested/applied/source disclosure, plus an effective-settings inspection command.S6 — Numeric argument errors are unstructured. A negative
limitpasses the schema gate's coarse type check and ends as a free-text deserialization error, without the accepted range that a misspelt argument name gets. Proposal: extend the shared validator to declared bounds and translate deserialization failures into the structuredinvalid_argumentscontract.Also from review of the train: public reference documentation should live under
docs/. The complete package-profile reference currently sits in_prdoc/guides/80-package-authoring.mdand is linked fromdocs/operations.md.Existing guards and what they do not cover:
crates/daemon/tests/argument_registry_e2e.rsderives the optional RPC arguments and proves each changes the daemon's answer. It does not cover config keys, CLI flags, environment variables, MCP-only arguments, defaults, precedence or documentation.Acceptance: one registry from which schema constraints, help text and the reference are generated or checked; a test that fails when an argument, key or variable exists without an entry; the acceptance matrix per tool family; structured errors for every out-of-range value.
Released in v0.41.50 (first part).
docs/mcp-arguments.md, compared with the schema in both directions by a test.invalid_argument_valuereplaces ten older codes; the four malformed-argument codes share one field set (error,tool,query,received,accepted,default,hint). Every other error body is unchanged; nineteen are compared with bodies recorded from v0.41.49.arguments_applied.response_format: "concise"is accepted bylist_files,get_dependenciesandresolution_gaps.tools/listis smaller than in v0.41.49 (59,167 against 59,311 bytes).Still open:
path_globandlangoutput filters on the reference, dependency and diff tools (eleven cells, listed as planned exemptions in the reference), additive aliases,limiton the diff tools, and the same registry for configuration keys, environment variables, CLI flags and durations. #575 (found in this train's CI) belongs to the same policy:search_text.queryhas no length bound, and a very long literal costs quadratic time in the FTS5 phrase parser.Findings for the configuration half of this issue, from writing
docs/configuration.mdagainst the code (branch for the next release, not released yet). The reference lists every accepted.code-index.tomlkey and every environment variable the release binaries read; a test compares the key table with the decoder's field lists in both directions.What the inventory showed:
watcher.mode,watcher.poll_interval_ms,logging.level,logging.format,workspace.name,plugins[].file. They are accepted, the diagnostics warn about them, and nothing else reads them. The reference marks each "no effect". Open question for the registry: keep accepting them with a warning, or refuse them like an unknown key after a deprecation period.CODE_INDEX_RECONCILE_INTERVAL_MS,CODE_INDEX_WAL_CHECKPOINT_MS,CODE_INDEX_SCHEMA_CHECK_MS,CODE_INDEX_ACTIVATION_POLL_MS,CODE_INDEX_RECONCILE_DELAY_MS,CODE_INDEX_READ_SPAN_TOCTOU_DELAY_MS. The last one is a fault-injection delay whose own comment says production never sets it. The reference lists them in a separate table as not recommended. They should either become stated settings or move behind the debug/test-seam guard other fault injection already uses.COSI_CORPUS_DIRandCOSI_WORKTREES_DIRare read by the shipped MCP server to expose linked projects; the names read as test switches.[watcher]config comments and the diagnostic say no polling backend exists; the watcher engages a polling fallback automatically when native delivery is not observed. The reference describes the actual behaviour.One registry for arguments, settings and their bounds: consistent acceptance, names, defaults and errors across CLI, config, env and MCPto Arguments, settings and documented facts disagree or lack one checked sourceStatus after v0.41.52: unchanged in this release. Still open and waiting for an operator decision: the six test timing hooks that release binaries still read, and the six configuration keys without effect that are still accepted with a warning.
Operator decisions, 2026-11-13 (asked as two concrete questions, answered in the session):
watcher.mode,watcher.poll_interval_ms,logging.level,logging.format,workspace.name,plugins[].file): refuse after one release. The next release keeps accepting them and its warning says that the key has no effect and will be refused from the release after it. From that release on they are refused like any unknown key.CODE_INDEX_RECONCILE_INTERVAL_MS,CODE_INDEX_WAL_CHECKPOINT_MS,CODE_INDEX_SCHEMA_CHECK_MS,CODE_INDEX_ACTIVATION_POLL_MS,CODE_INDEX_RECONCILE_DELAY_MS,CODE_INDEX_READ_SPAN_TOCTOU_DELAY_MS): debug builds only. Release binaries ignore them.Both are being implemented in a lane now.
This release still accepts six configuration keys without effect, but warns that they will be refused from the next release on; remove them from
.code-index.toml. Six test timing hooks remain readable by release binaries; making them debug-only is prepared for the next release.