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.
- Governing ADRs:
ADR-104,ADR-115,corpus-atlas-ADR-001,leafconfig-ADR-001,leafconfig-ADR-002 - Verification Suites:
ServerConfigAtlasAndHarvesterTest,LeafConfigRuntimeAndBitTest,FuzzySearchEngineTest,test_discord_doc_index.py,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)¶
3+Edit Distance on Unknown Tokens (rduisss,tlprtdly,zzzqwx):- Why it fails: At Levenshtein distance
>= 3, short configuration identifiers collide across unrelated domains (e.g.minY,maxY,menu,mode). - System behavior:
FuzzySearchEngine.isFuzzyMatchcapsmaxDistat2(forlen >= 8) and1(forlen 4..7).ServerConfigAtlas.search("rduisss tlprtdly zzzqwx", ...)returns[](0false positives), andcombinatorial_retrievereturns zero high-confidence hits. 1- to2-Character Gibberish Queries ("tp no wk"):- Why it fails:
_tokenize_querydrops non-numeric tokens shorter than2characters andFuzzySearchEngineenforcesminLen >= 4. - System behavior: Only
tpsurvives tokenization;SupportBotEngine.handle_new_threadabstains 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)¶
- Immediate Turn-1
step_by_stepElevation (_update_user_intelligence_profile): - 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?"). - 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 anyinspect_novice_config_pastefinding immediately transition totechnical_tier = "step_by_step"on Turn 1. - The
config.ymlvs.definitions/regions/default.ymlOverride Trap: - When a user complains that editing
config.ymlhad no effect ("i changed config.yml and nothing happened"),handle_new_threadexplicitly appends: > Why editingconfig.ymldid not take effect: Region-level settings inplugins/RTP/definitions/regions/default.yml(such asshape.radius,vert.maxY, andvert.requireSkyLight) override the fallbackdefaults.*block inconfig.yml. Editdefinitions/regions/default.yml(or use/rtp editor) and run/rtp reload. - 1–3 Line Informal Config Paste Recovery (
inspect_novice_config_paste): - Even when a user pastes just 1–2 lines without Markdown code fences (
openOnBareRtp = no,raduis: 4800 blocks),inspect_novice_config_pasteresolves the fuzzy leaf keys via LCA (resolve_config_leaf_via_lca), injects the canonical keys intocombinatorial_retrieve, and renders a copy-pasteable**Config input & syntax fixes:**checklist plus a/rtp reloadreminder.
4.2 Conversation & Semantic Breaking Points (Failures by Design)¶
- Multi-Turn Zero-Diagnostic Loop Cap (
MAX_BOT_REPLIES_PER_THREAD = 3/clarifications_asked): - If a user posts a vague complaint (
"server lags"/"broken"), provides zero logs, configs, or/rtp testoutputs 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. - On explicit refusal, it sends a single self-serve grace reply and stays silent on repeated zero-delta refusals (
H-07,L-02). OnceMAX_BOT_REPLIES_PER_THREADis reached with newly supplied diagnostics, it performs a one-time handoff to#bot-triage-queue(🚨 Escalated,M-04). - Semantic Inversion Without Symptom Context:
- If a user sets
requireSkyLight: truethinkingtrueenables underground/cave teleports,trueis schema-valid (@type: boolean). Unless the user mentionscaveorundergroundin their message (which activates thecave_skylightconcept cluster and explainsrequireSkyLight: false), a standalone paste ofrequireSkyLight: trueis 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