Skip to content

Novice User Input, Fuzzy Query & Triage Boundary Calibration

This document records the deterministic tolerance rules, auto-coercion mechanics, success cases, and exact failure/breaking-point boundaries across FuzzySearchEngine (yaml-api), ServerConfigAtlas (config-bit-api), LeafConfigRuntime & the Web IDE Helper Bot (LeafConfig), corpus-atlas, and discord-support-bot. Every success case and breaking-point threshold cited below is verified by automated tests in ServerConfigAtlasAndHarvesterTest, LeafConfigRuntimeAndBitTest, test_discord_doc_index.py, and test_discord_support_bot.py.


1. Operating Point & Summary Success vs. Failure Matrix

When non-technical or hurried server operators configure plugins or ask for help in Discord, two opposing failure modes must be balanced: 1. Zero Silent Corruption on Ambiguous or Dangerous Inputs (S-004 / Schema Firewall): Auto-coercion must never invent numbers from prose words, silently accept out-of-range values that violate @range safety bounds, or match 3-edit-distance gibberish onto unrelated critical settings. 2. High First-Turn Recovery on Sloppy Human Inputs: Operators routinely write openOnBareRtp = no, teleportDelay: 5 seconds, radius: 4,800 blocks, indent YAML with hardware \t tabs, glue compound words together (netherroof, tpdelay, chestmenu), or edit config.yml defaults.* without realizing definitions/regions/default.yml overrides it.

Summary Calibration & Breaking-Point Matrix

User Mistake Level Input Category & Examples System Outcome Governing Component & Verification Test
Level 1: Sloppy / Informal Syntax (Success) openOnBareRtp = no, teleportDelay: 5 seconds, radius: 4,800 blocks, \t tab indentation, smart quotes “5000”, trailing ; Auto-coerced & explained (false, 100 ticks / 5 s, 300 chunks, = -> :, 2-space indent) ServerConfigAtlas#coerceInput, coerceYamlText, build_doc_index#coerce_informal_config_value (ServerConfigAtlasAndHarvesterTest, test_discord_doc_index.py)
Level 2: Heavy Typos, Compounds & Slang (Success) "stop chestmenu poping up", "tpdealy", "netherroof bedrcok", "spawn in dirt undergorund", "fix spwan timer", "raduis" Resolved to canonical AST symbol (addons/guimenu.yml#openOnBareRtp, teleportDelay, vert.maxY, shape.radius) _NOVICE_COMPOUND_AND_TYPO_MAP, _THESAURUS_CONCEPT_CLUSTERS, FuzzySearchEngine, ServerConfigAtlas#search
Level 3: Operator Workflow Traps (Success) "i edited config.yml radius and nothing changed", 1-3 line bare config pastes without code blocks Caught on Turn 1 (step_by_step tier); explains definitions/regions/default.yml overrides config.yml defaults.* and reminds /rtp reload SupportBotEngine#_update_user_intelligence_profile, inspect_novice_config_paste (test_discord_support_bot.py)
Level 4: Ambiguous Bare Numbers < 1000 (Boundary) radius: 400 in default.yml (user meant 400 blocks, omitted blocks unit) vs radius: 5000 (no unit) radius: 400 accepted literally as 400 chunks (6,400 blocks, plausible chunk radius); radius: 5000 (>= 1000) flagged (5000 chunks = 80,000 blocks -> suggests 312 chunks) inspect_novice_config_paste (test_discord_doc_index.py)
Level 5: Prose Math, Compound Units & 3+ Edit Typos (Hard Blocked / Escalated) teleportDelay: five seconds, cooldown: 1m 30s, maxMSPT: 500.0, spawn-mode: zzzz_unknown, "rduisss tlprtdly", "tp no wk" Hard-blocked (valid = false / @range firewall) or routed to ⏳ Needs Info / Logs intake; never guesses or corrupts disk ServerConfigAtlas#coerceInputForNode, DirectiveValidator, verify_llm_draft_against_schema (ServerConfigAtlasAndHarvesterTest, test_discord_support_bot.py)

2. Spelling, Run-On Compounds & Symptom-to-Mechanism Search Boundaries

2.1 Auto-Recovered Query Cases (Successes)

Mechanism Supported Input Pattern Concrete Examples Resolved Canonical Target
Length-Scaled Levenshtein Matching (FuzzySearchEngine) <= 1 edit on tokens of length 4..7; <= 2 edits on tokens of length >= 8 (minLen = 4) raduis -> radius, cricle -> CIRCLE, sky_islnd -> SKY_ISLAND, cave_flor -> CAVE_FLOOR arena.radius, shape.name, waves.spawn-mode
Curated Novice Compound & Phonetic Map (_NOVICE_COMPOUND_AND_TYPO_MAP) Glued run-on compounds and multi-transposition typos common in Discord support tpdelay, tpdealy, netherroof, chestmenu, bookmenu, movecancel, spawnradius, openonbarerpt, requireskylgiht, cooldwon, invulnerbility teleportDelay, vert.maxY, openOnBareRtp, cancelDistance, shape.radius, vert.requireSkyLight, teleportCooldown, invulnerabilityTime
Colloquial Symptom-to-Mechanism Clusters (_THESAURUS_CONCEPT_CLUSTERS & SYNONYM_MAP) Zero-jargon descriptions of player-visible symptoms "stop menu popping up", "spawn in dark underground", "budge and it quits", "wait time before teleport", "how to fix spwan timer" addons/guimenu.yml#openOnBareRtp, vert.requireSkyLight, cancelDistance, teleportDelay, waves.spawn-interval-ticks
OCR Kerning Decompounding (decompound_ocr_text) Lowercase tokens glued together by narrow Minecraft font kerning in screenshots invalidcommandargument, movedtooquickly, openonbarertp invalid command argument, moved too quickly, openOnBareRtp

2.2 Search & Lookup Breaking Points (Failures by Design)

  1. 3+ Edit Distance on Unknown Tokens (rduisss, tlprtdly, zzzqwx):
  2. Why it fails: At Levenshtein distance >= 3, short configuration identifiers collide across unrelated domains (e.g. minY, maxY, menu, mode).
  3. System behavior: FuzzySearchEngine.isFuzzyMatch caps maxDist at 2 (for len >= 8) and 1 (for len 4..7). ServerConfigAtlas.search("rduisss tlprtdly zzzqwx", ...) returns [] (0 false positives), and combinatorial_retrieve returns zero high-confidence hits.
  4. 1- to 2-Character Gibberish Queries ("tp no wk"):
  5. Why it fails: _tokenize_query drops non-numeric tokens shorter than 2 characters and FuzzySearchEngine enforces minLen >= 4.
  6. System behavior: Only tp survives tokenization; SupportBotEngine.handle_new_thread abstains from guessing config keys, applies ⏳ Needs Info / Logs, and prompts the user with the structured intake checklist (test_novice_user_modeling_informal_yaml_and_config_override_trap).

3. Configuration Value Coercion & YAML Syntax Sanitization Boundaries

3.1 Auto-Coerced Input & Syntax Cases (Successes)

Both ServerConfigAtlas#coerceInputForNode / coerceYamlText (Java, used by LeafConfigRuntime and the Web IDE) and build_doc_index#coerce_informal_config_value / inspect_novice_config_paste (Python, used by corpus-atlas and discord-support-bot) perform deterministic normalization with human-readable explanations:

Input Error Class Raw User Input Target Schema / Key Coerced Output Generated Explanation Note
Informal Booleans yes, y, yep, on, enabled, 1 / no, n, nope, off, disabled, 0 @type: boolean (e.g. openOnBareRtp, requireSkyLight) true / false Auto-coerced informal boolean 'no' -> 'false' for openOnBareRtp.
Seconds -> Ticks Conversion 2 seconds, 5s, 3 sec @unit: ticks or *-ticks (e.g. waves.spawn-interval-ticks) 40, 100, 60 Converted '2 seconds' -> '40' ticks (1s = 20 ticks) for waves.spawn-interval-ticks.
Minutes -> Ticks Conversion 1 minute, 2m @unit: ticks or *-ticks 1200, 2400 Converted '1 minute' -> '1200' ticks (1 min = 1200 ticks) for ...
Ticks -> Seconds Conversion 100 ticks, 40t @unit: seconds or *Delay / *Cooldown 5, 2 Converted '100 ticks' -> '5' seconds (20 ticks = 1s) for teleportDelay.
Blocks -> Chunks Conversion 4800 blocks, 4,800 blocks @unit: chunks (shape.radius, shape.centerRadius) 300 Converted '4800 blocks' -> '300' chunks (1 chunk = 16 blocks in shape.radius).
Percentage -> Probability 50%, 25% @type: double with @range: [0.0, 1.0] (*chance, *probability, *ratio) 0.5, 0.25 Converted percentage '50%' -> '0.5' decimal probability for ...
Formatting Noise & Quotes 1,024 blocks, “5,000”; @type: integer (arena.radius) 1024, 5000 Stripped inline unit 'blocks' from '1,024 blocks' for arena.radius.
Enum Casing & 1-2 Char Typos circle, rectangel, sky_islnd, cave_flor @options: [CIRCLE, SQUARE, RECTANGLE, ...] CIRCLE, RECTANGLE, SKY_ISLAND, CAVE_FLOOR Auto-corrected enum typo 'sky_islnd' -> 'SKY_ISLAND' for waves.spawn-mode...
Broken YAML = & \t Tabs \tspawn-interval-ticks = 3 seconds Any YAML file in coerceYamlText / inspect_novice_config_paste spawn-interval-ticks: 60 Replaced leading Tab indentation with 2 spaces per level + Converted 'spawn-interval-ticks = 3 seconds' to YAML 'spawn-interval-ticks: 60'
Single-Bound @range Clamp (ServerConfigAtlas) 5 ticks on @range: [20, null] waves.spawn-interval-ticks 20 Clamped waves.spawn-interval-ticks from 5 to minimum allowed 20.

3.2 Configuration Value & YAML Breaking Points (Failures by Design)

Failure Case Raw User Input Why Auto-Coercion Refuses System Action
Spelled-Out Prose Numbers teleportDelay: five seconds, spawn-interval-ticks: twenty Parsing English number words risks misinterpreting prose comments or string values as numbers. coerceInputForNode returns valid = false, wasCoerced = false, note: "Expected integer for waves.spawn-interval-ticks, got 'five seconds'." Blocked by DirectiveValidator.
Compound Multi-Unit Expressions teleportCooldown: 1m 30s, radius: 2x16, delay: 10-20 Scalar numeric regex only accepts a single numeric literal + optional unit suffix (^(-?\d+)\s*(unit)?$). coerceInputForNode returns valid = false, wasCoerced = false; DirectiveValidator blocks disk write with @type violation.
Severe Enum Typos (3+ Edits) spawn-mode: zzzz_unknown_mode, shape.name: HEXAGON Not in @options and edit distance exceeds FuzzySearchEngine threshold (maxDist <= 2). coerceInputForNode returns valid = false ("Value 'zzzz_unknown_mode' is not one of the valid options..."); Discord bot schema firewall rejects shape.name: HEXAGON (H-02, H-03).
Out-of-Range LLM / Operator Recommendations maxMSPT: 500.0 (@range: 20.0 - 50.0), minTPS: 10.0 Exceeding 50.0 ms tick budget or dropping minTPS floor causes server stalls. verify_llm_draft_against_schema rejects draft (outside @range); DirectiveValidator blocks commit (RANGE_VIOLATION).
Ambiguous Bare Numbers < 1000 on Chunk Keys radius: 400 (user meant 400 blocks, did not write blocks) 400 chunks (6,400 blocks) is a valid, common survival region radius (default is 256 chunks). Only bare numbers >= 1000 (16,000+ blocks) can be flagged as likely block-vs-chunk confusion without false-positiving on legitimate chunk radii. radius: 400 is accepted literally as 400 chunks; radius: 5000 triggers the block-vs-chunk warning (5000 blocks -> 312 chunks).
Destroyed YAML Section Hierarchy Deleting parent shape: / vert: headers or flattening nested keys to root Line-level coerceYamlText repairs \t tabs and key = value, but cannot reconstruct deleted parent section headers without risking cross-section misattribution (M-09). RtpYamlConfig / extract_non_default_yaml_overrides infers section context only when sibling keys (minY, maxY, requireSkyLight) are present; otherwise rejects malformed structure.

4. Discord Support Bot Novice Modeling & Triage Loop Boundaries

4.1 Novice Turn-1 Detection & Operator Trap Recovery (Successes)

  1. Immediate Turn-1 step_by_step Elevation (_update_user_intelligence_profile):
  2. Previously, technical_tier = "step_by_step" only activated after Turn 2+ if a user asked a meta-clarification question ("how do I run /rtp test?").
  3. Now, Turn-1 posts matching novice signals ("how do i edit/find/open/reload", "where is the config/file/folder", "i changed config.yml and nothing happened", "idk how", "im new to") or containing any inspect_novice_config_paste finding immediately transition to technical_tier = "step_by_step" on Turn 1.
  4. The config.yml vs. definitions/regions/default.yml Override Trap:
  5. When a user complains that editing config.yml had no effect ("i changed config.yml and nothing happened"), handle_new_thread explicitly appends: > Why editing config.yml did not take effect: Region-level settings in plugins/RTP/definitions/regions/default.yml (such as shape.radius, vert.maxY, and vert.requireSkyLight) override the fallback defaults.* block in config.yml. Edit definitions/regions/default.yml (or use /rtp editor) and run /rtp reload.
  6. 1–3 Line Informal Config Paste Recovery (inspect_novice_config_paste):
  7. Even when a user pastes just 1–2 lines without Markdown code fences (openOnBareRtp = no, raduis: 4800 blocks), inspect_novice_config_paste resolves the fuzzy leaf keys via LCA (resolve_config_leaf_via_lca), injects the canonical keys into combinatorial_retrieve, and renders a copy-pasteable **Config input & syntax fixes:** checklist plus a /rtp reload reminder.

4.2 Conversation & Semantic Breaking Points (Failures by Design)

  1. Multi-Turn Zero-Diagnostic Loop Cap (MAX_BOT_REPLIES_PER_THREAD = 3 / clarifications_asked):
  2. If a user posts a vague complaint ("server lags" / "broken"), provides zero logs, configs, or /rtp test outputs across multiple turns, or explicitly refuses to share logs (DIAGNOSTIC_REFUSAL_RE: "I won't upload my server config"), the bot does not guess or loop indefinitely.
  3. On explicit refusal, it sends a single self-serve grace reply and stays silent on repeated zero-delta refusals (H-07, L-02). Once MAX_BOT_REPLIES_PER_THREAD is reached with newly supplied diagnostics, it performs a one-time handoff to #bot-triage-queue (🚨 Escalated, M-04).
  4. Semantic Inversion Without Symptom Context:
  5. If a user sets requireSkyLight: true thinking true enables underground/cave teleports, true is schema-valid (@type: boolean). Unless the user mentions cave or underground in their message (which activates the cave_skylight concept cluster and explains requireSkyLight: false), a standalone paste of requireSkyLight: true is treated as a valid surface-only configuration.

5. Reproducing the Calibration & Boundary Suites from Source

Run the automated Java and Python verification suites directly from the repository root:

# 1. Run the Java ServerConfigAtlas, FuzzySearchEngine, and LeafConfigRuntime suites
./gradlew :yaml-api:test :config-bit-api:test :resource:LeafConfig:leafconfig-common:test --info

# 2. Run the Python Corpus Atlas & Discord Support Bot novice success/failure boundary suites
python3 -m unittest discord-support-bot/tests/test_discord_doc_index.py discord-support-bot/tests/test_discord_support_bot.py discord-support-bot/tests/test_corpus_atlas.py discord-support-bot/tests/test_web_relay_and_triage.py -v