leafconfig-ADR-001 - Universal Server Config Atlas, Third-Party JAR Introspection, and Web IDE Workspace¶
Status: Accepted Date: 2026-10-27 Formerly: ADR-127 Extends: ADR-126, corpus-atlas-ADR-001, leafrtp-ADR-080, leafrtp-ADR-082, yaml-api-ADR-001, yaml-api-ADR-003
Context¶
A production Minecraft server (Paper, Folia, Purpur, Velocity, Fabric, NeoForge) typically hosts 30 to 80 plugins or mods, each exposing its own .yml, .toml, .json, or .properties files alongside engine configs (server.properties, bukkit.yml, spigot.yml, paper-global.yml, paper-world-defaults.yml, purpur.yml, velocity.toml). Server operators face four structural problems when configuring a server:
- Fragmented or Missing Documentation: Operators must cross-reference dozens of external wikis, GitHub READMEs, and Discord channels to understand what a configuration key does, what units it expects, and whether changing it requires a restart.
- Comment Stripping and Lost Defaults: Many third-party Bukkit/Paper plugins call
JavaPlugin#saveConfig()on boot or reload, stripping inline YAML comments from disk and leaving operators with bare key-value pairs and no visibility into the original author defaults. - Unchecked Cross-File and Cross-Plugin Interactions: Settings in one file routinely reference entities defined in another (world names, regions, permission groups, materials) or conflict with mechanics governed by another plugin or engine file (e.g., despawn ranges, view distance vs. chunk queue depth, sleep percentage).
- Absence of Schema Directives in Third-Party Configs: While
DailyStruggle/RTPplugins declare explicit# @type,# @range,# @options, and# @unitdirectives (yaml-api-ADR-003), third-party plugins do not.
The monorepo already provides the core building blocks required to solve this at the whole-server level:
- corpus-atlas (build_doc_index.py and corpus_atlas.py): hierarchical YAML key extraction, Lowest-Common-Ancestor (LCA) key disambiguation (resolve_config_leaf_via_lca), SQLite FTS5 + fts5vocab indexing, and typed AST edges/conflicts (corpus-atlas-ADR-001).
- yaml-api and config-bit-api: comment-preserving YAML parsing (RtpYamlSection), directive parsing (DirectiveSchemaParser, DirectiveValidator), and cross-file validation (ReferenceSettingCheck, GenericConstraintCheck).
- leafrtp-ADR-080 and leafrtp-ADR-082: zero-inbound-port ephemeral Web IDE with a signed two-way editor channel, Contextual Doc Tracker drawer, and Staging Diff Inspector, complemented by menu-api (MenuDescriptor, MenuSession) for in-game Book and Chest GUI lowering.
Decision¶
Generalize the configuration indexing, validation, and Web IDE stack into a standalone, multi-loader server configuration atlas and workspace (LeafConfig), operating across all installed server engine and third-party plugin configurations without requiring third-party plugin cooperation.
1. Three-Plane Config & Metadata Harvester (JarConfigScanner)¶
LeafConfig harvests configuration structure, defaults, comments, and code references across three planes off the main tick thread:
- Plane 1 — Embedded JAR Introspection (Read-Only
ZipFileScan ofplugins/*.jar&mods/*.jar): - Artifact Metadata: Parses
plugin.yml,paper-plugin.yml,bungee.yml,velocity-plugin.json,fabric.mod.json, andMETA-INF/neoforge.mods.tomlto recordartifact_id,display_name,version,authors,website, registered commands, permissions, and plugin dependencies (depend/softdepend). - Pristine Embedded Defaults & Comments: Extracts shipped
.yml,.toml,.json, and.propertiesresources directly from inside each JAR archive. Comparing Plane 1 defaults against Plane 2 disk files yields exactjar_default_valuebaselines, user-modified diff flags (is_modified), and restorable author comments even when a third-party plugin'ssaveConfig()stripped comments from disk. - Bytecode Constant-Pool String Scan (
< 5 msper JAR, Zero Classloading): ScansCONSTANT_Utf8entries in.classfiles inside each JAR for configuration key literals passed to configuration accessors (getBoolean,getInt,getDouble,getString,getStringList,getConfigurationSection) andEnum.valueOftargets. This discovers undocumented/hidden keys and emitsREAD_BY_CLASSAST edges linking config keys directly to the Java classes and commands that consume them. - Plane 2 — Live Server Disk Working Tree:
- Scans engine configuration files (
server.properties,bukkit.yml,spigot.yml,paper-global.yml,paper-world-defaults.yml,purpur.yml,velocity.toml) and active plugin/mod directories (plugins/<Plugin>/**,config/**). - Computes live values (
live_disk_value) and structural diffs against Plane 1 defaults. - Plane 3 — External & Pre-Baked Knowledge Packs:
- Curated Engine & Ecosystem Atlas: Ships a pre-baked SQLite/JSON knowledge slice covering standard server engine files (
Paper,Folia,Purpur,Spigot,Velocity) andLeaf*plugins. - Automated External Doc Retrieval: Uses JAR SHA-512 hashes (
api.modrinth.com/v2/version_file/<sha512>) and artifact metadata URLs to fetch official README/Wiki Markdown during offline or opt-in indexing, linking prose sections to dotted config keys viacorpus-atlasLowest-Common-Ancestor (LCA) disambiguation. - Local GPU Synthesis Backfill (
corpus-atlas-ADR-001Pattern): Where third-party keys lack documentation, optional offlineP2synthesis combines Plane 1 default YAML with bytecode consumer context to generate structured doc cards, stamped with explicit provenance (doc_provenance = 'LLM_SYNTHESIZED').
2. Deterministic Schema Inference for Untagged Configs (SchemaInferrer)¶
When a third-party configuration file lacks explicit yaml-api-ADR-003 # @type / # @range / # @options directives, SchemaInferrer synthesizes structured directives_json deterministically from three signals:
- Value Literal & Key-Suffix Heuristics:
- Boolean literals (
true/false) ->@type: boolean. - Keys ending in
-ticks,-ms,-seconds,-delay,-cooldown,-interval,-duration->@type: integer(orduration),@unit: ticks|ms|s,@range: [0, null]. - Keys ending in
-radius,-distance,-chunks,-blocks,-max,-limit,-count,-size,-threads->@type: integer,@range: [0, null]. - Keys ending in
-chance,-multiplier,-rate,-percent,-weight,-ratio->@type: double. - Keys matching
world,worlds,*-world->@type: reference,@source: server:worlds. - Keys matching
material,block,item,biome,sound,particle,enchantment,entity-type->@type: enum,@source: minecraft:<registry>. - Prose Comment Regex Extraction:
- Extracts enum options from contiguous
#comments matching patterns such asValid values: A, B, CorOptions: [X | Y | Z]into@options. - Extracts numeric bounds from comments matching
between X and Y,(X - Y), or-1 to disableinto@range. - Bytecode Enum Constant Extraction:
- When Plane 1 bytecode analysis observes a config key passed into
Enum.valueOf(TargetEnum.class, ...),SchemaInferrerpopulates@optionswith the enum constants declared inTargetEnum.class.
3. Crosslinked Config Atlas Schema (doc-index.sqlite Extension)¶
Extend the corpus-atlas SQLite schema (build_doc_index.py and corpus_atlas.py) with three tables and four cross-file AST edge kinds:
config_artifacts:- Keyed by
artifact_id(engine:paper,plugin:leafrtp,plugin:essentialsx, etc.), storingdisplay_name,version,loader_family,jar_sha512,doc_source_url,commands_json,permissions_json, andreload_strategy. ast_config_nodes:- Keyed by
symbol_id(cfg:<artifact_id>:<file_path>#<key_path>), storingartifact_id,file_path,key_path,parent_prefix,leaf_name,jar_default_value,live_disk_value,is_modified,inferred_type,directives_json,reload_tier(HOT_RELOAD,PLUGIN_RELOAD,SERVER_RESTART), anddoc_provenance(AUTHOR_COMMENT,OFFICIAL_DOCS,BYTECODE_INFERRED,LLM_SYNTHESIZED). ast_entity_bindings:- Generalized cross-file reference index mapping
(entity_kind, entity_value, symbol_id, role)whereentity_kindisWORLD,REGION,PERMISSION_GROUP,MATERIAL,BIOME, orFILE_REF, androleisDEFINESorREFERENCES. - Cross-File & Cross-Plugin
ast_edgesPredicates: INHERITS_FROM_KEY: Links override keys to their baseline definitions (e.g.,leafrtp-ADR-055@<file>inheritance orpaper-world-defaults.yml-> per-world overrides).COUPLED_BOUND: Captures mathematical or capacity invariants across keys in the same or different files (e.g.,spigot.yml#view-distance<->LeafRTP#performance.queueSize).CONFLICTS_WITH_KEY: Flags overlapping or contradictory mechanics across plugins (surfaced inast_conflicts, e.g.,LeafSleepvs.EssentialsX/ vanillaplayersSleepingPercentage).READ_BY_CLASS: Linkscfg:<artifact>:<file>#<key>tocls:<fully_qualified_class>from Plane 1 bytecode scanning.
4. Web IDE Workspace Primary Surface & In-Game menu-api Parity¶
LeafConfig reuses the leafrtp-ADR-080 / leafrtp-ADR-082 4-panel Web Editor architecture as its primary operator interface, alongside optional in-game menu-api Book/Chest lowering:
- Panel 1 — Multi-Plugin File Tree & Symptom-to-Config Omni-Search:
- Groups configurations by Server Engine, Installed Plugins, and Addons, displaying modified-key count badges (
SUM(is_modified)). - Provides client-side FTS5 + IDF +
ast_edgessearch (CAUSES_SYMPTOM,REMEDIATED_BY,GOVERNED_BY_KEY) so natural-language symptom queries rank exact YAML keys across all installed plugins. - Exposes a 2D / 3D World Map Viewport Toggle (
setMapViewMode('2d' | '3d'),drawMap3D) with interactiveYaw,Pitch,Zoom, andX-Ray Y Cutoffcontrols rendering multi-span terrain columns, tabulated plugin spatial zones, selection beacons, and 3D lag trigger volumes (Sleuth3DLagVolume), fed with client-side drawing code and packet-budgeted.hca v2/.dlshblock and $16^3$ sub-chunk slices viaWorldBlockFeed. - Panel 2 — Schema-Aware YAML Editor & Plane 1 Comment Restoration:
- Renders type-appropriate widgets (
@type,@range,@options,@unit) and overlays Plane 1 author comments when disk files have had comments stripped by third-party plugins. - Provides a per-key Reset to JAR Default (
jar_default_value) action. - Panel 3 — Crosslinked Contextual Doc Tracker Drawer:
- Selecting any key displays its documentation card with explicit
doc_provenancebadge, inferred schema,reload_tier, cross-file entity usages (ast_entity_bindings), coupled bounds (COUPLED_BOUND), and cross-plugin conflict warnings (CONFLICTS_WITH_KEY). - Panel 4 — Staging Diff Inspector & Pre-Commit
PBITGate: - Validates all staged edits across touched files in memory via
DirectiveValidator,GenericConstraintCheck, and generalizedReferenceSettingCheck(ast_entity_bindings) before writing.bakbackups and committing changes over the signed editor channel.
Alternatives Considered¶
| Alternative | Why Rejected |
|---|---|
Require third-party plugin authors to integrate a LeafConfig Java API |
Zero adoption at launch; fails to help operators with the 50+ legacy or third-party plugins already in their plugins/ directory. |
Parse only live disk .yml files (ignore plugins/*.jar archives) |
Loses pristine jar_default_value baselines, cannot restore comments stripped by JavaPlugin#saveConfig(), and misses bytecode READ_BY_CLASS and enum constants. |
| Classload third-party plugin classes during config scanning | Triggers static initializers and Bukkit classloader side effects; read-only ZipFile + constant-pool scanning extracts strings and enum constants in < 5 ms with zero classloading. |
| In-game chest GUIs as the sole configuration interface | Chest GUIs cannot ergonomically display multi-file search results, full prose documentation, cross-plugin conflict graphs, or side-by-side unified YAML diffs; the leafrtp-ADR-080 Web Panel is primary, with menu-api retained for quick in-game edits. |
Consequences¶
- Positive:
- Server operators gain a single searchable Web IDE and knowledge atlas across Paper/Folia/Purpur/Velocity and every installed plugin, complete with restored comments, default diffs, and cross-plugin conflict warnings.
- Third-party plugins gain rich schema validation (
@type,@range,@options) automatically viaSchemaInferrerand Plane 1 JAR introspection, while plugins that adoptyaml-api-ADR-003comment directives get first-class schema control with zero JAR dependencies. - The baked
ast_config_nodesandREAD_BY_CLASSgraph feeds directly intodiscord-support-bot, cross-server fleet sync (leafconfig-ADR-002), andLeafSleuthlag attribution (leafsleuth-ADR-003). - Negative / Trade-offs:
- Initial boot or reload scanning of 50+ plugin JARs requires bounded off-thread
ZipFileI/O, mitigated by caching Plane 1 extractions keyed byjar_sha512. - Inferred schemas (
BYTECODE_INFERRED/LLM_SYNTHESIZED) can be less specific than author-writtenyaml-api-ADR-003directives and must always display theirdoc_provenancebadge and allow raw YAML override in the Web Panel.
References¶
- leafconfig-ADR-002 (Selective Cross-Server Fleet Config Synchronization and Third-Party Plugin Lifecycle Control)
- leafsleuth-ADR-003 (Heuristic Lag Attribution with Confidence Intervals and Web Panel Heatmap-to-Config Remediation Bridge)
- yaml-api-ADR-001, yaml-api-ADR-003
- corpus-atlas-ADR-001 (
corpus-atlas/build_doc_index.py,corpus-atlas/corpus_atlas.py) - leafrtp-ADR-080, leafrtp-ADR-082
api/config-bit-api(DirectiveSchemaParser,DirectiveValidator,ReferenceSettingCheck,GenericConstraintCheck)api/menu-api(MenuDescriptor,MenuSession)