Blacksite/.cursor/plans/deterministic_asset_fingerprints_2026-07-13.plan.md

Deterministic Imported-Asset Fingerprints

Scope

Implement Gitea #56 so imported-source identity is content-addressed and editor/validator runs do not rewrite project artifacts because checkout timestamps or serialization whitespace changed.

Contract

• Persist one shared fingerprint for imported model, texture, and audio sources: byte length plus a BLAKE3 digest of the exact source bytes.
• Do not persist or compare source mtimes as semantic identity. Legacy timestamp fields remain readable but are ignored.
• Static-mesh and animation manifests use the same content identity as the asset registry.
• Preserve stable registry UUIDs across metadata-only drift and uniquely identifiable source moves.
• Before writing a registry or generated manifest, compare the parsed semantic document; preserve the existing bytes when the result is equivalent.
• Project validators stay read-only and validate both length and digest, including same-size edits.

Implementation

1. Add the shared fingerprint type and migrate animation/static-mesh contracts.
2. Persist fingerprints for model, texture, and audio registry records and generalize move recovery.
3. Make registry and manifest publication semantic and byte-preserving.
4. Extend static-mesh and registry validation plus focused migration/read-only tests.
5. Update ADRs, asset-pipeline docs, CI clean-worktree assertion, and committed generated artifacts.

Verification

• Focused editor and scene tests for mtime-only drift, same-size changes, legacy manifests, byte-preserving equivalent refresh, imported source kinds, and read-only validation.
• Formatting, diff check, clippy, and workspace all-target tests.
• Native editor startup and asset refresh with before/after Git status and source timestamp drift.
• cargo validate-levels --project . and cargo validate-samples --project ., followed by a clean worktree assertion. Packaged-runtime tests remain deferred by owner direction.