feat(miner): add mask() — RFC 0001 §6.2 step 2

[jensholdgaard]

Summary

Second Red → Green building block for the miner. Implements the
masking layer per RFC 0001 §4.2 / §6.2 step 2: a token classified
as a known shape is replaced with its type tag in the masked
sequence and captured as a typed parameter. The tree walk routes
against the type tag (per §4.2's modification of paper-Drain);
reconstruction (§6.6) walks the parallel typed_params to recover
the original line bytes.

What's in this PR

• ParamType enum with all RFC §6.1 variants (Ip, Uuid,
  Num, Hex, Ts, Path, Str, Overflow). Only the first
  three have a mask() emitter in this PR; the others are
  reserved on the enum because the Parquet record schema (§6.1)
  is the data contract.
• Masked<'a> { tokens, typed_params } position-preserving
  output (tokens.len() == input.len() always); zero per-token
  allocation, value: &'a str borrows directly from the input.
• mask() walks the input slice once, applying classify()
  per token. Rule precedence is UUID > IPv4 > NUM (most
  specific first), so a 36-char UUID is not misclassified as
  NUM and a dotted quad is not parsed as a digits-and-dots
  NUM-shaped string.
• Hand-rolled classifiers — no regex dep yet:
  • is_uuid — 8-4-4-4-12 hex digits with - separators.
  • is_ipv4 — four 0..=255 octets, leading-zero rejection.
  • is_num — integers with optional leading -.

What's not in this PR (deferred, with reason)

• Hex / Ts / Path rules — need richer rule shapes than the
  hand-rolled classifiers; deferred to a future masking-rule PR
  that probably introduces the regex dep.
• Str emitter — RFC §6.2 step 5b says Str is captured by
  template widening (when a previously-fixed literal becomes a
  wildcard slot), not by the mask pass. Belongs to the widening
  PR.
• Overflow emitter — RFC §6.5 says Overflow is emitted by the
  per-parameter byte-limit check. Belongs to the byte-limit PR.
• Per-tenant configurable rules — RFC §4.2 commits to
  configurable masking; this PR ships only the hardcoded default
  rule set. Configuration interface is a separate PR.

Tests (AAA-structured per the new policy starting this PR)

7 unit tests in mask.rs:

• mask_matches_rfc_section_3_5_worked_example — anchor test
  pinning the implementation against the RFC's own §3.5 example
  (user 42 logged in from 10.0.0.1 → user <NUM> logged in from <IP>). Covers IP, NUM, multiple literals, and positional
  preservation in one assertion.
• mask_classifies_uuid — UUID-specific path.
• mask_classifies_negative_integer_as_num — signed handling.
• mask_unrecognized_tokens_stay_literal — pure-literal negative
  test.
• mask_typed_param_value_borrows_from_input — pointer-equality
  check that pins the lifetime contract: a bug calling
  .to_string() somewhere would still pass string-equality
  assertions but fail this.
• is_ipv4_rejects_octet_above_255 / _rejects_leading_zero_octet
  — boundary cases on the parser that prevent silent
  over-acceptance.

Lifecycle

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

• Outer loop (cargo test --all-features):
  10 passed, 28 ignored. New tests are 7 mask + 3 existing
  tokenize/regression. The 28 ignored stubs are unchanged.
• Inner loop (cargo test --no-fail-fast -- --ignored):
  28 failed, unchanged.

This PR adds infrastructure that no §5 scenario directly exercises
yet. Per docs/verification.md §2.4 ("normative not exhaustive")
and §8's "Unit tests for tree operations" technique, mask() is
covered by unit tests now and will be exercised end-to-end by
future PRs that wire tokenize → mask → tree descend → attach.
The §5 scenario count toward Green is unchanged at 1/29. RFC
0001 stays at status: red.

Invariant / hazard impact (CLAUDE.md §§3, 4)

• §3.7 (per-tenant template trees). mask() is currently
  per-process (no tenant ID parameter). This is fine for the
  hardcoded default rule set; once per-tenant configurable rules
  land, the MaskingRules struct will be per-tenant.
• H1 (template miner correctness). mask() precedence is
  documented and tested (UUID > IPv4 > NUM); silent
  misclassification is the hazard, the precedence test pins it.
• H2 (parameter cardinality blowup). Not addressed yet —
  OVERFLOW emitter is the byte-limit PR's responsibility.

Test plan

• cargo fmt --all --check clean
• cargo clippy --all-targets --all-features -- -D warnings clean
• cargo test --all-features — 10 passed, 28 ignored
• mdbook build clean (no doc changes, but verified)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Implements the miner’s token masking layer (RFC 0001 §4.2 / §6.2 step 2): classifies tokens by shape and replaces matched tokens with <TYPE> placeholders while capturing the original token bytes as typed parameters for later reconstruction.

Changes:

• Added mask module with ParamType, TypedParam, Masked, and mask() implementing UUID/IPv4/NUM masking with documented precedence.
• Added hand-rolled classifiers (is_uuid, is_ipv4, is_num) and unit tests covering RFC example + boundary cases.
• Exported the new mask module from ourios-miner crate root.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
crates/ourios-miner/src/mask.rs	Introduces masking types + mask() and classifiers, plus unit tests validating RFC behavior and edge cases.
crates/ourios-miner/src/lib.rs	Exposes the new mask module publicly.

---

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