Format normalisation

These rules define the result objects of conformance/{zelim,boranko,comics}/expected/*.json; the Rust (media server), Dart (freedome_protocol) and TypeScript codecs must produce the same values (JSON value equality, key order irrelevant) and the same problem codes / pointers. Reference: tools/sniff/formats.mjs.

Common

• Text is decoded as UTF-8 (strict) after stripping one leading BOM EF BB BF (fixes the Latin-1 decode in Sphere comics_service.dart:61); invalid UTF-8 / JSON → validation-failed pointer "".
• Unknown keys are kept; enums are open (unknown values kept verbatim, clients map them to UNKNOWN).
• Paths inside a project are relative to the project root (the .zelim file’s directory, the _boranko/ folder, the ZIP root): /-separated, no .. segment, not absolute, no backslash, drive letter, URI scheme or NUL — violations → validation-failed with the JSON pointer of the field.
• Major version ≠ 1 → unsupported-format; a newer minor is read with the newest known schema (unknown keys kept).
• Warnings are strings <code> or <code>:<pointer>; compared order-insensitively.

.zelim JSON project (variant J)

Result {format: "zelim", variant: "json", formatVersion, schema, project} — project is the document as parsed (no defaults injected; audio, comics, settings stay absent when absent). schema = the minor whose schema validated it (1.0 for 1.0.x, 1.1 for 1.1.x and newer 1.x). 1.1 quantum.scene: when the referenced file exists next to the project its size, sha256 and binary validity are checked (validation-failed /quantum/scene/size / /quantum/scene/sha256); when it is missing → warning quantum-scene-missing. Writers SHOULD omit settings.recentProjects (local paths).

.zelim binary (variant B, formats/zelim-binary.ksy)

Result {format: "zelim", variant: "binary", version, timestamp, compression, elements[], groups[], metadata} in the v2 model for both versions:

• element {id, parentId, orbitAngle, radius, phase, energyLevel, quantumState, attractionCoefficient, conservationFactor, interactionMatrix[9]} — v1: parentId = 4294967295 (root), 8 stored matrix values + 9th = 0, v1 id (u64) must fit u32;
• group {id, energyTransferRate, collisionThreshold, groupType, members[]} — v1: non-zero slots (0 = empty), v2: the first memberCount slots (0 is a valid id);
• compression: as stored, empty → "none" (v1 quantum_lz4 is informative: never applied);
• metadata: the parsed JSON block. Length checks before every read (64-bit arithmetic: offset + count × size ≤ file size); problem pointers name the header field (/elementsOffset, /groupsOffset, /metadataOffset, /metadata, /compression, /flags, /groups/<i>/memberCount). v2 requires explicit offsets and flags = 0; trailing bytes are ignored. Writers emit v2 only; the reference upgrade (tools/gen/zelim_bin.py upgrade_v1) is pinned by samples/zelim/legacy.v1-upgraded.v2.zelim.

.boranko

Result {format: "boranko", variant, formatVersion, schema, project}; project = data.json with reader defaults applied before schema validation: version 1.0.0; page fileName = imagePath, originalPath “”, zDepth 100 and clamped to 0..108 (warning zdepth-clamped:<pointer>), domeOptimized / quantumCompatible false, text null, sounds / balloons []; sound startTime 0, volume 1; balloon type “speech”, aspectRatio 1, analogDigitalCoefficient 0.5; localizations {}; assets null, or with originalImages / vectorizedImages [] and balloonsOriginalPath assets/balloons_original, balloonsCleanedPath assets/balloons. Single-JSON files are 1.0 (no layerId). For the folder / zip forms every referenced file that is absent gives a warning missing-file:<pointer> (not an error: Sphere tolerates missing assets).

.comics

data variant result: {format: "comics", variant: "data", width, height, layers[], sounds[], extra, entries}: layer {id: "layer_<i>", images[] (as stored, {} slots kept), animations[]}, sound {id: "sound_<i>", file, animations[]}, animation {kind: translate | scale | rotate | sound | unknown, $type, params} (kind from the $type class-name suffix, params = the other keys verbatim); extra = unknown root keys; entries = sorted non-directory ZIP entry names. Warnings: missing-file:/sounds/<i>/file, missing-tiles:/layers/<i>/images/<k>. Tile template expansion ({0}_{1}_{2}) is not part of the result yet. Legacy variant: {format: "comics", variant: "legacy", pages (metadata.pages or the image entries sorted by name), metadata (metadata.json / info.json or null), entries}.