feat(proof): name the topic_id / custom_id hyphen-underscore mix-up (Architecte follow-up 4/4)

[echobt]

Summary

Architecte / Owner follow-up 4 of 4 (topic_id ↔ custom_id slug alignment). Based on main; independent of the other three.

The mix-up. Topic ids are hyphen slugs ([a-z0-9][a-z0-9-]{1,62}); metric.custom_id, checklist ids and PROOF_VM_RUNNER_CUSTOM_IDS are identifiers that may carry underscores ([a-z0-9][a-z0-9_-]{1,63}), and the runner is looked up by custom_id byte-for-byte. Staging used staging-fc-colo-test for the topic and staging_fc_colo_test for the metric, and every rejection just printed the regex.

Decision: keep both rules, document the canonical mapping, make every message explain it. Loosening the topic slug would touch a URL path segment, the VM / jail / nftables names, and the DB CHECK (topic_id ~ '^[a-z0-9][a-z0-9-]{1,62}$') in 0020_proof_rlm.sql; tightening custom ids would break signed topics and rule ids that already use _. Neither is worth it for a UX problem, so the UX is fixed instead:

• proof-canon: slug_hint / custom_id_hint (why it is malformed — "topic ids are slugs with hyphens only — underscores belong to metric.custom_id / checklist ids", "lower-case only", "no whitespace" — plus a corrected form: did you mean "staging-fc-colo-test"?), id_twin (the registered id that equals this one up to _ ↔ - / case), twin_suffix. Namespace doc on is_slug / is_custom_id.
• proof-task: TopicError::BadId carries the hint; new TopicError::BadCustomId { id, hint } names metric.custom_id (was a generic BadBinding); UnknownCustomMetric { id, twin } names the registered twin: custom metric "staging_fc_colo_test" has no registered runner on this host; a topic may draft but not open (ids match byte-for-byte: "staging-fc-colo-test" is registered, and '_' is not '-'; use exactly that id in metric.custom_id / PROOF_VM_RUNNER_CUSTOM_IDS).
• proof-rlm: RunnerError::Unregistered { custom_id, twin } — the 503 miners and operators see carries the same twin sentence; RunnerError::BadCustomId (what PROOF_VM_RUNNER_CUSTOM_IDS: … skipped logs at boot) carries the hint and corrected form.
• Wire check: env explains byte-for-byte matching and that the topic id never looks a runner up; boot-probe suggests the slug form for a bad --probe-topic.
• Runbook § Identifiers: the mapping table (which id, which shape, where used, example), the canonical rule (runner ← metric.custom_id exactly; convention custom_id = slug with -→_ is a habit, not something code derives), and a "you did / you see" table of the new messages. docs/PROOF.md field table and the staging env example say the same.

Behaviour is unchanged for every well-formed input: same accept / reject decisions, same status codes; only error texts and two error-variant shapes (matched with { .. } at the 3 sites) changed.

How to verify

cargo test -p proof-canon -p proof-task -p proof-rlm -p proof-rlm-scorer -p proof-http -p proof-challenge-bin

Messages to expect (also in the runbook table):

You did	You see
topic id: "staging_fc_colo_test"	topic id "staging_fc_colo_test" must match [a-z0-9][a-z0-9-]{1,62}; topic ids are slugs with hyphens only — underscores belong to metric.custom_id / checklist ids …; did you mean "staging-fc-colo-test"?
metric.custom_id: "Staging FC"	topic binding metric.custom_id "Staging FC" must match [a-z0-9][a-z0-9_-]{1,63}; lower-case only; no whitespace; did you mean "staging_fc"?
topic opens with custom_id: staging_fc_colo_test, host registered staging-fc-colo-test	… has no registered runner … (ids match byte-for-byte: "staging-fc-colo-test" is registered, and '_' is not '-'; …) — at publish (400) and at submit (503, no row)
PROOF_VM_RUNNER_CUSTOM_IDS=Staging-FC	boot log custom id "Staging-FC" must match …; lower-case only; did you mean "staging-fc"?; skipped

Greptile

• Greptile has reviewed this PR; findings are fixed or answered
• If the bot was silent, I commented @greptileai review

Test plan

• cargo test --workspace (isolated target dir)
• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets -- -D warnings, cargo deny check, xtask loc-cap (proof-task 1490 / 1500) / consensus-lint / spec-check / design-check / external-docs-check

Risk

None to deploy, measurement, signature domains, or emission: no id rule changes, no schema change, no wire change. Error strings are longer; anything matching them by prefix (custom metric … has no registered runner, topic id … must match …) still matches.

Naming

I did not rename BASE_* environment variables, deployed host paths
(/opt/base, /run/base, …), GHCR baseintelligence/base package names, or
base-*-v1 cryptographic domain tags, unless this PR’s purpose is a coordinated
cutover documented in docs/NAMING.md.

  

[echobt]

@greptileai please review topic_id/custom_id slug hints (Architecte follow-up 4/4) after rebase onto main post-#252.

[greptile-apps]

Greptile Summary

This PR improves diagnostics and operator documentation for the distinct Proof identifier namespaces without changing identifier validation or lookup behavior. It explains topic IDs versus custom metric IDs, provides corrected identifier guidance, and propagates clearer failures through publication, runner resolution, scoring, deployment checks, and operator runbooks.

Confidence Score: 5/5

Safe to merge; there are no outstanding blocking issues.

The previously reported retry-suggestion issue was manually resolved without explanation by echobt. It is not outstanding.

_{Reviews (2): Last reviewed commit: "Merge branch 'main' into cursor/proof-to..." | Re-trigger Greptile}