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

SymbolicPlan.save() cryptographically hashes every persisted artifact into 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. The method persists:

• 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, 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 uses sha256_file from src/yue2/storage.py to generate cryptographic hashes for every file:

# 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 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 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, 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; 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. 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:

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, *.npy, optionally score.abc) and creates a cryptographic manifest using SHA-256 hashes in 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. Additionally, it validates that the raw bytes match the abc field inside 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 that only accepts 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. 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 will be caught immediately and raise ValueError before the corrupted data reaches the generation stage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}