Observer internals

Observer internals

Observer is a separate Rust path in the elah administrator binary. It inspects offline Minecraft Java Anvil worlds without depending on a running server.

Read boundary

Production Observer code opens observed inputs read-only. It accepts regular files under one selected world root, rejects symbolic links and special entries, and does not expose write, repair, rename, delete, or lock operations.

Standard mode

Standard mode:

1. discovers the safe world tree;
2. reads bounded level.dat metadata;
3. identifies vanilla and namespaced dimensions;
4. validates every .mca region header;
5. validates each occupied chunk envelope;
6. aggregates counts, bytes, bounds, storage share, and timestamps;
7. repeats report-driving evidence collection before success.

It does not decompress chunk NBT.

Deep mode

Deep mode also:

• fingerprints complete terrain and external chunk inputs;
• decompresses each occupied chunk within fixed limits;
• validates NBT structure and sequence bounds;
• checks embedded chunk coordinates where available;
• aggregates chunk data-version and status distributions.

Supported chunk compression identifiers cover GZip, Zlib, uncompressed NBT, Java LZ4-block streams, and external .mcc data.

Two-pass consistency

Observer collects evidence before and after aggregation. Added, removed, replaced, redirected, resized, or changed report inputs invalidate the observation.

The result is exit code 5 with no success report. Advanced details list only a bounded, sorted set of affected paths.

Contracts

• Successful JSON schema: elah.observe/v1
• Error JSON schema: elah.error/v1
• Standard output: one success document only
• Standard error: progress notices and errors

Integer fields are checked before JSON serialization so values that JavaScript would round are rejected rather than silently changed.

Independent oracle

PrismarineJS packages create and reread deterministic fixture truth in development and CI. They do not ship in the Observer binary and do not define the production filesystem boundary.

Read ADR 0007 for the accepted design decision.