refactor(miner): split MaskTag from ParamType for exhaustiveness

[jensholdgaard]

Summary

Pure refactor of crates/ourios-miner/src/mask.rs, surfaced
during PR #11 review discussion. Replaces the
(ParamType, &'static str) tuple that classify() returned with
a private MaskTag enum covering only the masking-emit subset
(Uuid, Ip, Num).

Issue with the original code:

fn classify(token: &str) -> Option<(ParamType, &'static str)> {
    if is_uuid(token)      { Some((ParamType::Uuid, "<UUID>")) }
    else if is_ipv4(token) { Some((ParamType::Ip,   "<IP>")) }
    else if is_num(token)  { Some((ParamType::Num,  "<NUM>")) }
    else                   { None }
}

Hand-coupled (variant, tag) strings at the call site with no
exhaustiveness check. Adding a fourth maskable variant tomorrow,
the compiler wouldn't have forced anyone to remember the tag.

What changed

• enum MaskTag { Uuid, Ip, Num } — private to the module
  (it's a masking-layer detail).
• MaskTag::as_str(self) -> &'static str — total exhaustive
  match; adding a MaskTag variant compiler-errors until you
  give it a tag.
• From<MaskTag> for ParamType — total exhaustive match;
  adding a MaskTag variant compiler-errors until you map it to
  the data-contract enum.
• classify() returns Option<MaskTag>; mask() calls
  tag.as_str() (infallible, no Option<&str> / no expect())
  and tag.into() for the typed-param tag.
• Module + ParamType doc comments updated to mention MaskTag.

Why MaskTag is separate from ParamType

• ParamType is the data contract (RFC §6.1) — variants
  like Str (emitted by widening), Overflow (emitted by
  byte-limit check), and the future Hex / Ts / Path don't
  have masking-time tag strings.
• A tag() method on ParamType would be
  Option<&'static str> with most variants returning None,
  leaking the "this method only really applies to a subset"
  awkwardness into the public API.
• The masking-layer tag-string format (<NUM>, <IP>) is
  also likely to grow Drain3-style named slots
  (RFC §4.5: <IP:client_addr>) on per-tenant configurable
  rules — keeping the tag concern inside the masking layer
  makes that change a one-spot edit.

Regression tests added (per the new edge-case-from-review policy)

• mask_tag_as_str_pins_canonical_strings — pins
  MaskTag::Uuid.as_str() == "<UUID>" etc. so a future rename
  of the &'static str literals fails loudly here rather than
  silently changing the on-the-wire masked-token sequence the
  tree walk routes against.
• param_type_from_mask_tag_pins_mapping — pins the From
  mapping so a refactor that swapped two arms (e.g.
  accidentally mapping MaskTag::Ip to ParamType::Uuid) would
  still type-check but silently mis-attribute typed-param data
  on the wire.

No behaviour change

Existing mask_* tests assert against the literal <UUID> /
<IP> / <NUM> strings and still pass unchanged. §5 scenario
count toward Green is unchanged at 4/29 — this is a pure
refactor, no stubs flip.

Lifecycle

Per docs/verification.md §3 two-loop spec:

• Outer loop (cargo test --all-features):
  13 → 15 passed (+2 new regressions); 25 → 25 ignored.
• Inner loop (cargo test --no-fail-fast -- --ignored):
  25 → 25 failed, unchanged.
• §5 scenario count toward Green: 4/29 (unchanged).

RFC 0001 stays at status: red.

Test plan

• cargo fmt --all --check clean
• cargo clippy --all-targets --all-features -- -D warnings clean
• cargo test --all-features — 15 passed, 25 ignored
• mdbook build clean (no doc changes, but verified via prior runs)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Refactors ourios-miner’s token-masking implementation to decouple “maskable-at-emit-time” tags from the broader ParamType data-contract enum, improving exhaustiveness guarantees while keeping behavior unchanged.

Changes:

• Introduced a private MaskTag enum representing only the mask-emittable subset (Uuid/Ip/Num), plus an exhaustive as_str() mapping.
• Updated classify() to return Option<MaskTag> and adjusted mask() to derive both the tag string and ParamType via total functions (as_str() and From<MaskTag>).
• Added regression tests pinning the canonical tag strings and the MaskTag -> ParamType mapping.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.