feat(gateway): spike runtime settings file

[TaylorMutch]

Summary

SPIKE: Investigate a general gateway runtime settings file that Kubernetes deployments can use as an authoritative hook for enabling and disabling runtime-level gateway settings without restarting the gateway.

This is intentionally framed as a spike PR. It proposes and exercises one concrete implementation path: a watched runtime settings file referenced from gateway.toml, reconciled into the existing gateway-global settings row, with Helm support for mounting the file from a ConfigMap.

Related Issue

N/A - spike investigation requested directly.

Changes

• Add optional runtime_config_path to gateway startup TOML.
• Add a runtime settings parser, validator, startup reconciler, and file watcher.
• Persist runtime file values through the existing global settings record so sandbox config revision flow remains unchanged.
• Treat keys present in the runtime file as file-managed and reject settings set/delete --global for those keys.
• Add Helm server.runtimeConfig.* values, a separate runtime ConfigMap template, mounts, and chart tests.
• Document the proposed model in gateway reference docs and architecture notes.

Spike Questions

• Is a watched file the right operator-facing hook for Kubernetes deployments, or should this become a controller/operator API later?
• Are file-managed-key semantics sufficient, or should a future design support full authoritative reset of omitted settings?
• Is polling metadata enough for ConfigMap-backed updates, or should a follow-up implementation use native filesystem watch support?
• Should the public API expose which settings are file-managed so CLIs and TUIs can explain locked keys before mutation?
• What HA behavior do we want when multiple gateway replicas reconcile the same runtime file against a shared database?

Testing

• mise run pre-commit passes
• cargo test -p openshell-server runtime_config -- --nocapture
• cargo test -p openshell-server runtime_managed_key -- --nocapture
• cargo test -p openshell-server config_file::tests::parses_full_example -- --nocapture
• mise run helm:test
• mise run helm:docs:check

Checklist

• Follows Conventional Commits
• Commit is signed off (DCO)
• Documentation updated for the spike behavior
• Draft PR: not ready for merge as final product design

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-1920.docs.buildwithfern.com/openshell