Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity
main
Blacksite/.cursor/plans/deterministic_asset_fingerprints_2026-07-13.plan.md

2.3 KiB
Raw Permalink Blame History

Deterministic Imported-Asset Fingerprints

Historical plan — not current implementation guidance. Use the documentation index for current behavior and architecture.

Status: Complete at cbd380a9413411667a83f74b66c5a2feda5e1af7; see docs/editor/evaluations/deterministic-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.