# How YuE SymbolicPlan Enforces Save Invariants and Prevents Tampered Scores via Manifest Hashing

> Discover how YuE SymbolicPlan enforces save invariants and prevents tampered scores. Learn about manifest hashing, completeness, and SHA-256 verification for secure data integrity.

- Repository: [multimodal-art-projection/YuE](https://github.com/multimodal-art-projection/YuE)
- Tags: internals
- Published: 2026-09-14

---

**`SymbolicPlan.save()` cryptographically hashes every persisted artifact into [`plan_manifest.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan_manifest.json), and `SymbolicPlan.load()` enforces strict completeness, whitelist, and SHA-256 verification to detect any modification of ABC scores or token arrays.**

The YuE music generation pipeline relies on `SymbolicPlan` to store intermediate symbolic representations between planning and audio synthesis stages. According to the multimodal-art-projection/YuE source code, this class implements a deterministic persistence protocol that guarantees downstream stages operate on exact, unmodified intermediate data.

## What Artifacts SymbolicPlan.save() Persists to Disk

When `save()` is invoked on a `SymbolicPlan` instance, it writes a deterministic set of files to the specified directory in [`src/yue2/pipeline.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/pipeline.py). The method persists:

- **[`plan.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan.json)** – Contains metadata, the request dictionary, timing information, a truncation flag, token lists, and optional ABC text, written via `write_json`【/cache/repos/github.com/multimodal-art-projection/YuE/main/src/yue2/pipeline.py#L35-L38】
- **`abc_tokens.npy`** – The ABC token IDs as a NumPy array, saved with `np.save`【...L33-L34】
- **`prefix.npy`** – The token prefix array, also saved with `np.save`【...L34】
- **`score.abc`** (optional) – The raw ABC score text, written only when ABC data is present【...L31-L32】

After writing these files, `save()` computes **SHA-256 digests** for each artifact and stores them in [`plan_manifest.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan_manifest.json), creating an immutable fingerprint of the complete plan state【...L40-L42】.

## Cryptographic Manifest Generation in plan_manifest.json

The manifest serves as the root of trust for plan integrity. The implementation in [`src/yue2/pipeline.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/pipeline.py) uses `sha256_file` from [`src/yue2/storage.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/storage.py) to generate cryptographic hashes for every file:

```python

# Artifacts are written, then manifest is created with SHA-256 digests

plan.save("/tmp/my_plan")  # Creates plan_manifest.json with file hashes

```

This [`plan_manifest.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan_manifest.json) maps each filename to its digest, ensuring any single-byte change in `abc_tokens.npy`, `prefix.npy`, or `score.abc` would invalidate the stored hash.

## How SymbolicPlan.load() Validates Integrity and Prevents Tampering

`SymbolicPlan.load()` implements a multi-layered validation strategy in [`src/yue2/pipeline.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/pipeline.py) that detects tampering through five specific checks. Only when **all** conditions pass does the method reconstruct the plan instance【...L62-L63】.

### Completeness and Whitelist Verification

First, the loader verifies the manifest contains the mandatory core files:

- **[`plan.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan.json)**, **`abc_tokens.npy`**, and **`prefix.npy`** must all be present【...L48-L50】
- Only known filenames are accepted; unexpected files or symbolic links are rejected【...L51-L52】

### SHA-256 Hash Verification

For every file listed in the manifest, `load()` recomputes the SHA-256 digest using `sha256_file` and compares it against the stored value. Any mismatch immediately raises a `ValueError`, signalling detected tampering【...L53-L54】.

### Data-Array Consistency Checks

The method loads `abc_tokens.npy` and `prefix.npy` and validates they are one-dimensional integer arrays. Their contents must exactly match the corresponding token fields stored inside [`plan.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan.json); discrepancies indicate file corruption or substitution【...L56-L59】.

### ABC Text Integrity Validation

If an ABC score is present, `load()` reads the raw bytes of `score.abc` and compares them byte-for-byte against the `abc` field in [`plan.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan.json). Any divergence raises `ValueError`【...L60-L61】.

## Practical Example: Detecting Score Tampering

The following code demonstrates the integrity guarantees. After saving a valid plan, manually corrupting the token file triggers detection on reload:

```python
from yue2.pipeline import SymbolicPlan, YuE2Pipeline
import numpy as np
import pathlib

# Create and save a valid plan

pipeline = YuE2Pipeline.from_pretrained("...")
plan = pipeline.plan(style="pop", lyrics="La la la")
plan.save("/tmp/my_plan")

# Tamper with the saved tokens

path = pathlib.Path("/tmp/my_plan/abc_tokens.npy")
np.save(path, np.array([0, 1, 2], dtype=np.int32))

# Loading detects the hash mismatch

try:
    restored = SymbolicPlan.load("/tmp/my_plan")
except ValueError as e:
    print("Tampering detected:", e)  # Raises due to SHA-256 mismatch

```

## Summary

- **`SymbolicPlan.save()`** writes deterministic artifacts ([`plan.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan.json), `*.npy`, optionally `score.abc`) and creates a cryptographic manifest using SHA-256 hashes in [`plan_manifest.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan_manifest.json).
- **Integrity verification** requires mandatory files to be present, rejects unknown files or symlinks, and recomputes file digests to detect any modification.
- **Data consistency checks** ensure NumPy array contents match JSON metadata and ABC text bytes remain unchanged from the original save.
- **Failure handling** raises `ValueError` immediately when any invariant is violated, preventing downstream stages from consuming corrupted symbolic data.

## Frequently Asked Questions

### What happens if I manually edit the ABC text in a saved plan?

`SymbolicPlan.load()` detects the modification by comparing the SHA-256 hash of `score.abc` against the digest stored in [`plan_manifest.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan_manifest.json). Additionally, it validates that the raw bytes match the `abc` field inside [`plan.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan.json). If either check fails, the method raises `ValueError` and refuses to load the tampered plan.

### Can I add extra files to a saved plan directory without breaking load?

No. The implementation enforces a strict whitelist in [`src/yue2/pipeline.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/pipeline.py) that only accepts [`plan.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan.json), `abc_tokens.npy`, `prefix.npy`, and optionally `score.abc`. Any additional files or symbolic links in the directory will cause `load()` to reject the plan with a validation error【...L51-L52】.

### Where are the hashing utilities implemented?

The `sha256_file` function and JSON serialization helpers are located in [`src/yue2/storage.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/storage.py). These utilities support the manifest creation and verification process used by both `save()` and `load()` operations in the pipeline.

### Does the hash verification protect against accidental disk corruption?

Yes. Since `SymbolicPlan.load()` recomputes SHA-256 digests for every artifact and compares them to the manifest values, any bit-rot, truncation, or accidental modification to `abc_tokens.npy`, `prefix.npy`, or [`plan.json`](https://github.com/multimodal-art-projection/YuE/blob/main/plan.json) will be caught immediately and raise `ValueError` before the corrupted data reaches the generation stage.