Document node.hostname config option (must be a bare hostname)

[dawsontoth]

Documents the node configuration section, which was missing from Configuration Options even though that page bills itself as covering all harper-config.yaml top-level sections, and records the node-identity behavior change that shipped in HarperFast/harper#2223.

node.hostname is this node's identity, not a URL: it becomes the node's TLS certificate common name and the host replication advertises to peers and dials to reach the node. A URL or host:port value silently corrupted both — a node configured as http://host:9926 advertised and dialed a host literally named http (HarperFast/harper#2218).

Companion to HarperFast/harper#2223, which is now merged. That PR landed as a loud rejection at the config boundary, not the warn-only change it was originally scoped as, so this docs PR was rewritten to match what actually shipped.

What this documents

• New ## node section in the config reference, placed immediately before ## replication (identity is defined right before the section that consumes it).
• The bare-host requirement, as enforced: a bare hostname, IPv4 literal, or unbracketed IPv6 literal is valid; a scheme, port, path, credentials, query string, fragment, bracketed [::1], or non-string value is rejected and Harper fails to start.
• replication.hostname too — harper#2223 put it under the same constraint (it previously accepted string|number), so its bullet was updated rather than left alone.
• The full identity fallback chain — replication.hostname → host in replication.url → certificate common name → Operations API host → 127.0.0.1, skipping unusable derived sources.
• release-notes/v5-lincoln/5.3.md — a new page carrying the breaking-change entry, since an install with a URL/host:port hostname will fail to boot after upgrading.

For the human reviewer

Two calls here are the author's judgment and are the places to push back:

1. v5.3.0 is an assumption, not a derived fact. harper#2223 is merged to main but no tag contains it (latest is v5.2.4), so the ship version is not yet knowable from the repo. v5.3.0 was chosen on the reasoning that a breaking change won't ship in a patch. If it actually ships as v5.2.5, both <VersionBadge> values and the release-notes filename need renaming before release.
2. This publishes a 5.3 release-notes page before 5.3 exists. The release-notes sidebar is autogenerated from the directory, so merging adds a visible "5.3" entry for an unreleased version. That is deliberate (it is where the breaking change belongs) but it does surface early — worth a second opinion on whether to hold this file until the release is cut.

Smaller notes:

• No in-doc issue links in the reference page (per the earlier review round), but the release-notes page does link harper#2218 — that matches its own house style; 5.2.md links harper#2049 the same way.
• node.url is left undocumented. It exists in the new Joi schema, but node_url appears only in hdbTerms.ts with no consumer, so documenting it would advertise dead surface.
• replication.routes entries are explicitly called out as still accepting URLs in the release notes, because the route schema is not bare-host constrained and readers will otherwise over-apply the new rule.
• No admonition was added to the config reference: that page has zero admonitions and is a flat quick-reference, so the boot-failure consequence is carried in bold inside the bullet instead.

Verification

• npm run build — succeeds; document count 403 → 404 (the new 5.3 page). The two broken-anchor warnings it prints are pre-existing on unrelated pages (backups/overview, release-notes/v5-lincoln/5.1); the new #node / #replication anchors and the release-notes link into /reference/v5/configuration/options#node all resolve.
• npm run format:write then npm run format:check — clean.
• Rebased onto current main (12 commits) with no conflicts.
• Every documented claim was read off the merged core commit 08531e344, not the PR description: utility/nodeIdentity.ts (bareHostViolation — the exact accept/reject set), validation/configValidator.ts (bareHostConstraints on both node.hostname and replication.hostname, and that route hostnames are unconstrained), and server/nodeName.ts (getThisNodeName fallback order).

Review coverage

Authored by Claude Opus 4.8, revised by Claude Opus 5 after harper#2223 merged with different behavior. Accuracy verified by reading the merged core implementation directly. gemini-code-assist reviewed the earlier revision; its two comments were addressed (in-doc issue links removed; its suggested v5.2.0 badge was declined as already-shipped and replaced with the v5.3.0 badge above, with the caveat in item 1).

[gemini-code-assist]

Code Review

This pull request adds documentation for the new node configuration block and its hostname option in reference/configuration/options.md. The feedback suggests removing direct links to internal GitHub issues and pull requests to maintain clean, user-facing documentation, and recommends using the <VersionBadge> format to properly document the behavior change regarding startup warnings for invalid hostnames.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-632

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-632

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-632

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-632

This preview will update automatically when you push new commits.