Skip to content

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:

  1. 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.
  2. 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.
  3. 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).
  4. Absence of Schema Directives in Third-Party Configs: While DailyStruggle/RTP plugins declare explicit # @type, # @range, # @options, and # @unit directives (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:

  1. Plane 1 — Embedded JAR Introspection (Read-Only ZipFile Scan of plugins/*.jar & mods/*.jar):
  2. Artifact Metadata: Parses plugin.yml, paper-plugin.yml, bungee.yml, velocity-plugin.json, fabric.mod.json, and META-INF/neoforge.mods.toml to record artifact_id, display_name, version, authors, website, registered commands, permissions, and plugin dependencies (depend / softdepend).
  3. Pristine Embedded Defaults & Comments: Extracts shipped .yml, .toml, .json, and .properties resources directly from inside each JAR archive. Comparing Plane 1 defaults against Plane 2 disk files yields exact jar_default_value baselines, user-modified diff flags (is_modified), and restorable author comments even when a third-party plugin's saveConfig() stripped comments from disk.
  4. Bytecode Constant-Pool String Scan (< 5 ms per JAR, Zero Classloading): Scans CONSTANT_Utf8 entries in .class files inside each JAR for configuration key literals passed to configuration accessors (getBoolean, getInt, getDouble, getString, getStringList, getConfigurationSection) and Enum.valueOf targets. This discovers undocumented/hidden keys and emits READ_BY_CLASS AST edges linking config keys directly to the Java classes and commands that consume them.
  5. Plane 2 — Live Server Disk Working Tree:
  6. 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/**).
  7. Computes live values (live_disk_value) and structural diffs against Plane 1 defaults.
  8. Plane 3 — External & Pre-Baked Knowledge Packs:
  9. Curated Engine & Ecosystem Atlas: Ships a pre-baked SQLite/JSON knowledge slice covering standard server engine files (Paper, Folia, Purpur, Spigot, Velocity) and Leaf* plugins.
  10. 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 via corpus-atlas Lowest-Common-Ancestor (LCA) disambiguation.
  11. Local GPU Synthesis Backfill (corpus-atlas-ADR-001 Pattern): Where third-party keys lack documentation, optional offline P2 synthesis 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:

  1. Value Literal & Key-Suffix Heuristics:
  2. Boolean literals (true / false) -> @type: boolean.
  3. Keys ending in -ticks, -ms, -seconds, -delay, -cooldown, -interval, -duration -> @type: integer (or duration), @unit: ticks|ms|s, @range: [0, null].
  4. Keys ending in -radius, -distance, -chunks, -blocks, -max, -limit, -count, -size, -threads -> @type: integer, @range: [0, null].
  5. Keys ending in -chance, -multiplier, -rate, -percent, -weight, -ratio -> @type: double.
  6. Keys matching world, worlds, *-world -> @type: reference, @source: server:worlds.
  7. Keys matching material, block, item, biome, sound, particle, enchantment, entity-type -> @type: enum, @source: minecraft:<registry>.
  8. Prose Comment Regex Extraction:
  9. Extracts enum options from contiguous # comments matching patterns such as Valid values: A, B, C or Options: [X | Y | Z] into @options.
  10. Extracts numeric bounds from comments matching between X and Y, (X - Y), or -1 to disable into @range.
  11. Bytecode Enum Constant Extraction:
  12. When Plane 1 bytecode analysis observes a config key passed into Enum.valueOf(TargetEnum.class, ...), SchemaInferrer populates @options with the enum constants declared in TargetEnum.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:

  1. config_artifacts:
  2. Keyed by artifact_id (engine:paper, plugin:leafrtp, plugin:essentialsx, etc.), storing display_name, version, loader_family, jar_sha512, doc_source_url, commands_json, permissions_json, and reload_strategy.
  3. ast_config_nodes:
  4. Keyed by symbol_id (cfg:<artifact_id>:<file_path>#<key_path>), storing artifact_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), and doc_provenance (AUTHOR_COMMENT, OFFICIAL_DOCS, BYTECODE_INFERRED, LLM_SYNTHESIZED).
  5. ast_entity_bindings:
  6. Generalized cross-file reference index mapping (entity_kind, entity_value, symbol_id, role) where entity_kind is WORLD, REGION, PERMISSION_GROUP, MATERIAL, BIOME, or FILE_REF, and role is DEFINES or REFERENCES.
  7. Cross-File & Cross-Plugin ast_edges Predicates:
  8. INHERITS_FROM_KEY: Links override keys to their baseline definitions (e.g., leafrtp-ADR-055 @<file> inheritance or paper-world-defaults.yml -> per-world overrides).
  9. COUPLED_BOUND: Captures mathematical or capacity invariants across keys in the same or different files (e.g., spigot.yml#view-distance <-> LeafRTP#performance.queueSize).
  10. CONFLICTS_WITH_KEY: Flags overlapping or contradictory mechanics across plugins (surfaced in ast_conflicts, e.g., LeafSleep vs. EssentialsX / vanilla playersSleepingPercentage).
  11. READ_BY_CLASS: Links cfg:<artifact>:<file>#<key> to cls:<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:

  1. Panel 1 — Multi-Plugin File Tree & Symptom-to-Config Omni-Search:
  2. Groups configurations by Server Engine, Installed Plugins, and Addons, displaying modified-key count badges (SUM(is_modified)).
  3. Provides client-side FTS5 + IDF + ast_edges search (CAUSES_SYMPTOM, REMEDIATED_BY, GOVERNED_BY_KEY) so natural-language symptom queries rank exact YAML keys across all installed plugins.
  4. Exposes a 2D / 3D World Map Viewport Toggle (setMapViewMode('2d' | '3d'), drawMap3D) with interactive Yaw, Pitch, Zoom, and X-Ray Y Cutoff controls 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 / .dlsh block and $16^3$ sub-chunk slices via WorldBlockFeed.
  5. Panel 2 — Schema-Aware YAML Editor & Plane 1 Comment Restoration:
  6. 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.
  7. Provides a per-key Reset to JAR Default (jar_default_value) action.
  8. Panel 3 — Crosslinked Contextual Doc Tracker Drawer:
  9. Selecting any key displays its documentation card with explicit doc_provenance badge, inferred schema, reload_tier, cross-file entity usages (ast_entity_bindings), coupled bounds (COUPLED_BOUND), and cross-plugin conflict warnings (CONFLICTS_WITH_KEY).
  10. Panel 4 — Staging Diff Inspector & Pre-Commit PBIT Gate:
  11. Validates all staged edits across touched files in memory via DirectiveValidator, GenericConstraintCheck, and generalized ReferenceSettingCheck (ast_entity_bindings) before writing .bak backups 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 via SchemaInferrer and Plane 1 JAR introspection, while plugins that adopt yaml-api-ADR-003 comment directives get first-class schema control with zero JAR dependencies.
  • The baked ast_config_nodes and READ_BY_CLASS graph feeds directly into discord-support-bot, cross-server fleet sync (leafconfig-ADR-002), and LeafSleuth lag attribution (leafsleuth-ADR-003).
  • Negative / Trade-offs:
  • Initial boot or reload scanning of 50+ plugin JARs requires bounded off-thread ZipFile I/O, mitigated by caching Plane 1 extractions keyed by jar_sha512.
  • Inferred schemas (BYTECODE_INFERRED / LLM_SYNTHESIZED) can be less specific than author-written yaml-api-ADR-003 directives and must always display their doc_provenance badge and allow raw YAML override in the Web Panel.

References