Recipe Format

A recipe is a JSON file with the .remap extension that captures every byte-level change between an original and a modified ECU binary. It is the central data structure of the entire OpenRemap pipeline — produced by openremap cook, consumed by every validate and patch command.

Recipes are fully portable between the CLI and the API. A recipe cooked on the command line can be applied through the API and vice versa.

Format Version

The current format version is 4.5, recorded in schema_version at the top level. cook emits 4.4 by default (with the maps layer); cook --no-annotate-maps emits the lean 4.3 format; cook-volatile emits 4.5 (with the volatile section). diff-maps --recipe … --annotate upgrades an existing 4.3 recipe.

The version is checked during validation and patching. A recipe with an unrecognised format version will be rejected before any instructions are read.

Version history:

Parsers MUST ignore unknown top-level fields. New fields may be added in minor versions without breaking existing consumers.

Top-level Structure

{
  "type": "recipe",
  "schema_version": "4.5",
  "source": "full_cook" | "cook_volatile" | "tune_export",
  "application": "openremap-core" | "openremap-studio",
  "creator": { },
  "fingerprint": "",
  "metadata": { },
  "ecu": { },
  "statistics": { },
  "instructions": [ ],
  "volatile": { }
}

creator

Human author identity. No tool fields — tool provenance is carried by application and schema_version.

"creator": {
  "name": "pinx",
  "handle": "pinx",
  "id": "",
  "created_at": "2026-06-02T14:30:00Z",
  "signature": null,
  "trust_level": "COMMUNITY"
}

fingerprint

SHA-256 hash of (offset, ob, mb) tuples sorted by offset. Used for deduplication and corruption detection — same tune produces the same fingerprint regardless of metadata. Not tamper protection on its own; will be combined with creator.signature for cryptographic verification in the future.

"fingerprint": "sha256:00f727e8abf62d384acc4420b08fe8e5477f9d004c8d3a697bbaaa08fe2149f5"

metadata

Information about the files the recipe was built from.

"metadata": {
  "name": "Stage 1 — ME7.5",
  "description": "Increased idle timing, raised rev limiter",
  "tags": ["stage1", "rev-limiter"],
  "instruction_count": 42,
  "original_file": "stock.bin",
  "modified_file": "stage1_tune.bin",
  "original_size": 524288,
  "modified_size": 524288,
  "tune_id": null
}

A same-file-only recipe additionally carries "portability": "same_file_only" in metadata (produced by cook --allow-non-unique when non-unique anchors are present).

ecu

The identity of the ECU the recipe was built for. Every validation and patch operation checks this block against the target binary before touching a single byte.

All string fields are null when the identifier could not be extracted from the binary. New extractors added in future library versions will populate fields that were previously null without a schema change.

"ecu": {
  "manufacturer": "Bosch",
  "match_key": "me7.5__0261208592__367276",
  "ecu_family": "ME7.5",
  "ecu_variant": null,
  "software_version": "0261208592",
  "hardware_number": "0261208592",
  "calibration_id": "367276",
  "oem_part_number": "06A906032HJ",
  "platform": "VAG",
  "calibration_version": "0003",
  "serial_number": null,
  "dataset_number": null,
  "file_size": 524288,
  "sha256": "3a7bd3e2360a3f5c8d4e1b9f0a2c6d7e8b3f1a4e5c9d2b6f0e7a1c3d5e9b2f4",
  "cook_warnings": []
}

The match_key

match_key is the primary compatibility gate. It is a compound string in the form FAMILY::VERSION and is compared against the target binary's own match_key before any validation or patching begins.

How it is built depends on the ECU architecture:

If the target binary's match_key does not match the recipe's match_key, the operation is rejected immediately with a clear mismatch message. A null match_key in the recipe disables this check and falls through to byte-level validation.

cook_warnings

Non-fatal issues detected during cooking (full_cook only; always empty for tune_export):

• Identity mismatches between original and modified binaries
• Non-unique context anchors (when Force Save bypasses the uniqueness guard)
• Low-entropy context regions

These are surfaced in the UI so the user can review them before applying the recipe.

statistics

A summary of the diff. Informational only — not used during patching.

"statistics": {
  "total_changes": 42,
  "total_bytes_changed": 168,
  "percentage_changed": 0.032,
  "single_byte_changes": 10,
  "multi_byte_changes": 32,
  "largest_change_size": 8,
  "smallest_change_size": 1,
  "min_context_size": 32,
  "max_context_size": 512
}

instructions

An array of patch instructions. Each instruction describes one contiguous block of bytes that differs between the original and modified binary.

"instructions": [
  {
    "offset": 6699,
    "offset_hex": "1A2B",
    "size": 4,
    "ob": "AABBCCDD",
    "mb": "11223344",
    "ctx": "DEADBEEF112233445566778899AABBCCDDEEFF00112233445566778899AABBCC",
    "context_after": "CAFEBABE112233445566778899AABBCCDDEEFF00112233445566778899AABBCC",
    "context_size": 32,
    "ctx_entropy": 5.2,
    "ctx_unique": true,
    "ctx_expanded": false,
    "description": "Idle timing base offset",
    "flags": []
  }
]

Instruction fields

Instruction flags

Each flag is an object with:

CODE_AREA (confidence 1.0) marks an edit outside a calibration region (code/erased/mixed flash area) — a portability signal, since code differs across ECU revisions. It is advisory: the recipe patches identically with or without it.

ob and mb

All byte strings are uppercase hex with no separators. A 4-byte value is represented as 8 hex characters: "AABBCCDD".

ob (original bytes) is what the strict validator checks before patching. If the bytes at offset do not match ob exactly, the instruction fails validation and the patch is rejected.

mb (modified bytes) is what the patcher writes. The post-patch validator checks that mb is present at offset after the patch is applied.

ctx — the anchor

ctx is a window of bytes immediately preceding the changed block in the original binary. The default minimum size is 32 bytes (min_context_size), but the cook pipeline uses entropy-gated geometric expansion to ensure each anchor is both high-entropy and unique within the original binary:

1. Start with min_context_size bytes (default 32).
2. Compute Shannon entropy of the candidate context.
3. Search the entire original binary for ctx + ob.
4. If entropy < 2.5 bits/byte OR the pattern appears more than once, double the context size (64 → 128 → 256 → 512).
5. Repeat until both conditions are met, or max_context_size is reached.
6. If max_context_size is reached and the anchor is still non-unique: when require_unique=True (default), raise a hard error listing the failed instructions. When require_unique=False (--allow-non-unique), record the non-unique anchors as cook_warnings and proceed — the recipe is stamped metadata.portability = "same_file_only" and tune/validate enforce it via ecu.sha256 (see metadata.portability).

Quality metadata (ctx_entropy, ctx_unique, ctx_expanded) is stored per-instruction for downstream tooling.

context_after

context_after is the same-size window of bytes immediately after the changed block. During patching, it is appended to the search anchor — the patcher searches for ctx + ob + context_after (not just ctx + ob). This doubles the effective anchor length at zero cost.

The anchor search works as follows:

1. Read ob bytes at the exact offset recorded in the instruction.
2. If they match — apply the patch immediately.
3. If they do not match — search the region [offset - 2048, offset + 2048] for the pattern ctx + ob + context_after.
4. If found at a new offset — apply the patch at the shifted position.
5. If not found — the instruction fails with a diagnostic message.

source — full_cook vs tune_export

Safety Properties

• No blind writes. The patcher never writes mb without first confirming ob is present — either at the recorded offset or at a shifted position found via the anchor search.
• All-or-nothing validation. The strict validator checks every instruction before the patcher writes a single byte. A single failure aborts the entire operation.
• Identity gate. match_key and file_size are verified against the target binary before any instruction is read.
• Portable. Recipes contain no absolute paths, no machine-specific data, and no binary blobs. They are plain JSON and can be stored, versioned, shared, and diffed.

See also

• Cook command — how to create a recipe from two binaries
• Cook-volatile command — car-portable recipes with volatile-byte exclusion (schema 4.5)
• Tune command — one-shot validate → apply → verify
• Validate command — individual validation steps
• About OpenRemap — project overview and use cases

← Back to documentation

maps (schema 4.4)

An optional annotation layer that connects recipe instructions to the calibration maps they touch. Purely informational — the patcher and validators read only instructions and ignore maps entirely, so a 4.4 recipe patches exactly like a 4.3 one.

Lean by design: no cell grids are stored, only structural descriptors, axis values, probabilistic labels, and references into instructions.

"maps": [
  {
    "id": "m1",
    "offset": 227058,
    "cols": 32,
    "rows": 16,
    "cell_width": 2,
    "byte_order": "little",
    "stride": null,
    "x_axis": { "offset": 226962, "values": [0, 500, 800, 1600, "…"] },
    "y_axis": { "offset": 227026, "values": [0, 10, 25, 40, "…"] },
    "score": 0.977,
    "label": "fuel",
    "label_confidence": 0.72,
    "instruction_refs": [3, 7, 12]
  }
]

Assignment rules: tables are visited in descending scan-score order; each instruction is claimed by the first (highest-scoring) table whose cell bytes contain it. Contiguous tables use a pad-tolerant structural region (X axis start → data end, ±4 bytes — the scanner's pad guess can drift); compound halves are exact (their data is pinned at Y-end). At most 500 maps are stored. metadata.annotated_maps is true in annotated recipes.

volatile (schema 4.5)

An optional section produced by cook-volatile — the volatile-region classification of the recipe. It records which instructions were detected as touching vehicle-specific / volatile bytes (VIN records, verified checksum stores) and how the cooker acted on them. Purely informational for patching — the patcher and validators read only instructions and ignore volatile entirely, so a 4.5 recipe patches exactly like a 4.4 one. The audit command does use it for a volatile-aware subset-fingerprint + re-verify check.

"volatile": {
  "excluded": [
    {
      "index": 12,
      "offset": 123456,
      "offset_hex": "1E240",
      "size": 4,
      "kind": "VIN",
      "confidence": 0.95,
      "action": "excluded",
      "evidence": [ "overlaps VIN-structured record 'WVW…' at 0x1E240-0x1E251 (confidence 0.95, evidence: wmi, check-digit, year, …)" ]
    }
  ],
  "flagged": [],
  "summary": { "excluded_count": 1, "flagged_count": 0, "bytes_excluded": 4 }
}

Each finding (both lists):

With --no-exclude nothing is removed: all findings are recorded with action: "flagged" and summary.excluded_count is 0. Metadata flags: metadata.source = "cook_volatile", metadata.excluded_volatile = true|false, metadata.volatile mirrors the summary. See cook-volatile.