id: design: build-time defaults file — embed network defaults from an optional JSON file instead of only hardcoded consts

Source (raw conversation, verbatim)

From Drew's peer-discovery plan review, OpenCode session ses_2ec427b80ffeuCx6dCuANmiN6c ("Peer discovery plan review"), 2026-03-23:

"add no-gossip. can all the defaults be populated from a json file optional at build so the end result is equivalent hardcoded const? hardcoded -> build defaults file (build flag to replace instead of append -> users can add new values on serve launch (flag to skip defaults no-default-<>)"

Follow-up in the same session, same day, confirming the direction:

"yes no-gossip, built time defaults, and mdns. what is the most efficient way to build a static config file to embed? compile time can't parse this into a const on its own it has to be a string?"

Recovered by the WS-F2 raw-conversation mining pass (2026-11-04). The other two items in that confirmed trio landed: --no-gossip exists in the serve/CLI surface, and mDNS address lookup is wired in the peers command (iroh_mdns_address_lookup). The build-time defaults file did not.

Current state (verified 2026-11-04)

• Network defaults are hardcoded Rust constants — e.g. the discovery topic/secret pair DEFAULT_TOPIC / DEFAULT_TOPIC_SECRET in the discovery module, consumed as a pair by resolve_config (see id(discovery): resolve_config pairs a CLI topic/secret with the public default for the other half under --no-default-topic #4756 for the cascade and its pairing bug).
• Runtime overrides exist per-value for some defaults (CLI --topic / --topic-secret / --no-default-topic), resolved by a documented cascade.
• There is no build-time defaults file: grepping the tree finds no defaults-file mechanism, no build.rs in pkgs/id or id-core, and no issue designs one (the WS-F2 pass searched the full ID issue universe for it).

What to design

1. File format + contents. A JSON file, optional at build time, that can populate the network defaults today spread across constants: discovery topic + secret, relay set, DNS/discovery endpoints, gossip on/off default, and any other hardcoded network default the audit finds. Building with the file must produce a binary whose effective defaults are equivalent to building with the corresponding constants — the file is a source for the same values, not a second semantics.
2. Replace vs append. Per Drew's sketch: a build flag chooses whether the file's lists (e.g. relays) replace the built-in lists or append to them. The choice is per-build, recorded, and visible (see 5).
3. Embedding mechanics. Answer Drew's literal question — "compile time can't parse this into a const on its own it has to be a string?" Options to evaluate: include_str! + lazy parse at first use; a build.rs that parses the JSON and emits typed Rust constants (codegen); include! of a generated source file; or a const-format parser. Criteria: compile-time validation of the file (a malformed defaults file should fail the build, not the first run), binary size/startup cost, and how the Nix build supplies the file (flake input / --cfg / env var — note the crate currently has no build.rs, so adding one is itself a decision).
4. Runtime composition. How build-time defaults compose with the existing runtime cascade: serve-launch flags can still add values on top, and a --no-default-* style flag can skip the built-in defaults entirely (Drew's "flag to skip defaults"). Precedence must be one documented cascade, consistent with resolve_config's existing steps — and the topic/secret pair must keep resolving as a pair (the id(discovery): resolve_config pairs a CLI topic/secret with the public default for the other half under --no-default-topic #4756 lesson).
5. Provenance. A built binary should be able to report where its defaults came from (pure constants / defaults file + its hash / replaced vs appended), e.g. in a version/about surface — a distributor shipping a private-network build must be able to prove which defaults are inside it.

Why it matters

Distributors and private deployments (an intranet build with private relays/topics — cf. #5683's intranet mode) currently must patch Rust source to change network defaults. A defaults file makes "same code, different network" a build option instead of a fork, which is exactly the property Drew asked for: end result equivalent to the hardcoded consts, chosen at build time.

Open questions

• Which defaults are in scope for v1 — discovery topic/secret only, or the full network set (relays, DNS, gossip)?
• Replace/append granularity: one build flag for all lists, or per-list keys inside the file?
• Should the file format be the same JSON shape as any runtime config, so one file can serve both build-time and serve-time use?
• How does the Nix flake expose it (a package variant per defaults file?) without exploding the build matrix?

Relates: #4756 (the resolve_config pairing bug in today's cascade), #5671 (transport fallback — relays are among the defaults), #5674 (wire/transport adapters), #5683 (residency/intranet mode — a consumer of private-network builds). Found by WS-F2 (raw-conversation mining); epic #2056.