Let env vars, CLI flags and set_configuration reach 41 config params that were never registered

[DavidCockerill]

⊙ Problem

env.get, per-key env vars, CLI flags and set_configuration resolve a config name only through CONFIG_PARAM_MAP. 41 params that Harper or Harper Pro read were never registered:

• Six Harper Pro replication tuning params were inert everywhere. Harper Pro reads them with env.get, so even a value in the config file was ignored and the compiled-in default always won (Four replication config knobs are silently inert: env.get resolves only names registered in CONFIG_PARAMS harper-pro#734).
• The rest could be set only in the config file. replication.recordLocks, agent.systemPromptAppend and the per-section logging settings fell into this group. For each, the env var was dropped with no error, and set_configuration returned 400 unrecognized config parameter, even though the configuration docs say any YAML key maps to an env var and a CLI flag.

❓ Your call: Should this cover every unregistered param that is safe to expose, rather than only the six from harper-pro#734? I chose the wider set: each is one registry line, and it changes behavior only for someone who sets that param. Dropping an entry later is a one-line revert.

💡 Solution

Register them in CONFIG_PARAMS; utility/hdbTerms.ts is the only file changed:

• The six replication tuning params and replication.recordLocks.
• agent.systemPromptAppend.
• Per-section logging leaves (level, path, root, stdStreams, tag) for http, authentication, analytics, replication, storage and mqtt, plus http's timing, headers and id.
• The registry's doc comment now says what an unregistered param costs.

For example, REPLICATION_RECORDLOCKS=true is now written to harper-config.yaml at boot, set_configuration {"http_logging_level": "debug"} now writes http.logging.level, and Harper Pro's existing env.get('replication_receiveYieldInterval') now returns the configured value.

Harper Pro needs no code change. Its literal reads resolve once its core pointer includes this commit, and Sync Core will move the pointer. HarperFast/harper-pro#734 can be closed then.

What changes for existing installs:

• An env var or CLI flag with one of these names, previously ignored, now takes effect at the next boot.
• Once Harper Pro picks this up, a value for one of the six replication params that was already in a config file starts taking effect.
• A replicated set_configuration using one of the new names is rejected by peers that are not yet upgraded; their failures appear in response.replicated[]. Upgrade every node before setting these names cluster-wide.

⚖️ Alternatives

• Have getConfigValue fall back to the flattened config for unregistered names. Rejected: it fixes only reads. A write needs the canonical camelCase path, and an env-var name is case-folded, so env vars, CLI flags and set_configuration would still miss these params.
• Generate the registry from a schema, or let env.get resolve any valid path. Not done in a patch: neither schema is complete. The Joi schema accepts unknown keys, and config-root.schema.json is maintained by hand and already wrong for mqtt (mqtt.port instead of mqtt.network.port).

❓ Your call: The hand-kept registry is what drifted here, and it will drift again: #3064 and #3098 already add more entries. Should the switch to a schema-driven registry become its own issue?

• Register Harper Pro–only names in core. This follows the existing practice: core already registers more than 40 Harper Pro replication params, and Pro has no registry of its own.
• Register the mTLS revocation leaves too. These are the CRL/OCSP enabled switches and the mqtt certificateVerification tree. Rejected after review because it would widen a fail-open: …_OCSP_ENABLED=0 becomes the number 0, nested validation rejects it, and getCachedCertificateVerificationConfig then disables all revocation checking. Today that env var is simply ignored. These leaves need boundary validation before they are registered.
• Joi bounds for the six tuning params. Rejected: Joi runs at boot, so a dormant out-of-range value in a config file, inert until now, would stop a node from booting on upgrade.
• Harden Harper Pro's reads of the six params with finite parsing and timer-ceiling caps. Left out to keep this to one change. The six now behave like Harper Pro's other registered replication knobs, which use the same bare ?? default.

❓ Your call: The per-section logging leaves become writable per key, but nothing validates them. HTTP_LOGGING_ROOT=2024 is stored as a number, and join() then throws inside the logger's config listener; the error is logged, not fatal, and that logger stops picking up changes. A YAML value already does the same today. Should logging sub-schemas be added to each section here, or tracked separately? Adding them makes them run at boot.

• Left out on purpose:
  • operationsApi.network.mtls / mtls_required (operationsApi.network.mtls and mtls_required are unregistered config params — client-cert verification can never be enabled on the ops/replication ports #2641): flattenConfig makes operationsApi.network inherit http.*, so registering them would make every existing http.mtls: true config start requesting client certificates on the operations/replication port.
  • models.* (No models.* config params: a models block cannot be set via set_configuration, so the built-in agent cannot be given a model over the ops API #2267): a map of operator-named providers, which needs a design.
  • http.securityHeaders: its keys are operator-chosen header names; HARPER_SET_CONFIG already covers the JSON form.

✅ Verification

• End-to-end (route c, live smoke). I ran built Harper Pro at main (98698201), unchanged except core pinned to this commit, from a scratch ROOTPATH and HOME, with REPLICATION_RECEIVEYIELDINTERVAL=50, REPLICATION_RECORDLOCKS=1, HTTP_LOGGING_LEVEL=debug and AGENT_SYSTEMPROMPTAPPEND='Answer briefly.' set:
  • All four landed in harper-config.yaml and in get_configuration.
  • recordLockConfig logged replication.recordLocks is set to 1, which is not the boolean true on both main/0 and http/1, so the env value reached the reader on each thread. (1 was used on purpose, because only a non-boolean value produces that log line.)
  • set_configuration {"replication_copyCheckpointRecords": 500} succeeded and wrote replication.copyCheckpointRecords: 500.
  • The same run with base core wrote none of the four values, logged no recordLocks warning, and set_configuration returned unrecognized config parameter: replication_copyCheckpointRecords.
• Gates on this Mac. Every failure was rerun on a fresh build of the branch base, e73121e2c:
  • test:unit:main: 6709 passing. 20 failed: 19 identical on base, and bundleDependencies’ “retries a transient failure moving the candidate into place” passes when that file is rerun on the branch (a load flake). applicationSpawn.test.js was excluded because it hangs (test:unit:main hangs/flakes on macOS: applicationSpawn.test.js never finishes, EntryHandler.test.js first test times out ~4/6 #2538).
  • test:unit:resources: 4058 passing. 3 sourceApplyConflictRetry failures, identical on base.
  • test:integration:all: 2278 passing. 21 failures identical on base: isolated-application, shutdown-drain, record-lock concurrency, log rotation, rolling restart and cert-key-reload, which need more than one HTTP worker or a shorter UDS path. operation-denial-log failed once under load and passed 3/3 when run alone on the branch.

Closes #3099
Refs HarperFast/harper-pro#734

_{🤖 Generated by Claude Code (Anthropic Claude Opus); posted via @DavidCockerill.}

Related PRs: #2436 independent, #2532 independent, #3064 overlaps (adds AGENT_MAXTOKENS beside AGENT_SYSTEMPROMPTAPPEND; textual conflict only), #3098 overlaps (adds AGENT_CONFIGSCOPE beside it; textual conflict only), #3035 independent, #3117 overlaps (adds AGENT_MAXTOOLRESULTBYTES in the same AGENT_ block; textual conflict only)

Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; declined=cursor-grok,cursor-composer,cursor-kimi,cursor-muse; rounds=5; full=1 @ 0982896}

_{Review-Attention: read ~3m (decisions: per-leaf-logging-registration, pro-names-in-core-registry, per-key-env-surface-widened) @ 0982896}

[github-actions]

Release cherry-pick v5.3: merged

Cherry-picked onto v5.3.

[gemini-code-assist]

Code Review

This pull request updates utility/hdbTerms.ts to register several new configuration parameters in the CONFIG_PARAMS registry, including component-specific logging settings (for analytics, authentication, HTTP, replication, storage, and MQTT), replication tuning parameters, and an agent system prompt append option. Additionally, the documentation comment for CONFIG_PARAMS was updated to clarify how configuration parameters are resolved. No review comments were provided for this pull request, so there is no feedback to address.