Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity

BS-JD-209 - Deterministic imported-asset fingerprints #56

New Issue
Closed
opened 2026-07-13 01:00:50 -04:00 by Rbanh · 1 comment
Rbanh commented 2026-07-13 01:00:50 -04:00
Owner
Copy Link

Summary

Make imported-asset fingerprints and generated manifests deterministic so launching the editor or running validators does not dirty a clean checkout when source bytes are unchanged.

Why

Native #33 QA repeatedly rewrote the generated animation/static-mesh manifests for RobotExpressive.glb solely because the checkout/source mtime differed from persisted modified_unix_secs. The content hash and byte length were unchanged. Later validation also normalized only the final newline. These changes are repository noise, obscure intentional edits, and make clean-checkout release evidence unreliable.

Git does not preserve source mtimes, so persisting checkout timestamps as semantic identity cannot be stable across contributors or CI.

Implementation notes

  • Treat content identity as authoritative; mtime may accelerate scanning in memory but must not force a persisted rewrite when bytes/semantic output are unchanged.
  • Give every imported source kind a stable content fingerprint. Do not leave static meshes dependent on byte length + mtime alone.
  • Compare serialized semantic manifests before publishing; preserve exact committed bytes when the import result is equivalent.
  • Ensure read-only validation never mutates generated artifacts.
  • Migrate existing manifests compatibly without forcing unrelated asset reimports.
  • Keep registry UUIDs and sub-asset IDs stable across metadata-only drift.

Acceptance criteria

  • A fresh LFS checkout remains clean after native editor startup, asset scan, cargo validate-levels, and cargo validate-samples.
  • Touching an imported source without changing bytes produces no authored/generated diff.
  • Changing bytes with the same length is detected and refreshes the correct manifests.
  • Equivalent reimport output preserves exact file bytes, including formatting/newline.
  • Static mesh, animation, texture, audio, and model-source paths share the deterministic policy.
  • Tests cover mtime-only drift, same-size content change, old-manifest migration, and read-only validators.

Docs/tests

The content-addressed contract is owned by ADR 0043, integrated with ADRs 0017/0028, and enforced by the post-validator clean-worktree CI assertion.

Evidence

## Summary Make imported-asset fingerprints and generated manifests deterministic so launching the editor or running validators does not dirty a clean checkout when source bytes are unchanged. ## Why Native #33 QA repeatedly rewrote the generated animation/static-mesh manifests for `RobotExpressive.glb` solely because the checkout/source mtime differed from persisted `modified_unix_secs`. The content hash and byte length were unchanged. Later validation also normalized only the final newline. These changes are repository noise, obscure intentional edits, and make clean-checkout release evidence unreliable. Git does not preserve source mtimes, so persisting checkout timestamps as semantic identity cannot be stable across contributors or CI. ## Implementation notes - Treat content identity as authoritative; mtime may accelerate scanning in memory but must not force a persisted rewrite when bytes/semantic output are unchanged. - Give every imported source kind a stable content fingerprint. Do not leave static meshes dependent on byte length + mtime alone. - Compare serialized semantic manifests before publishing; preserve exact committed bytes when the import result is equivalent. - Ensure read-only validation never mutates generated artifacts. - Migrate existing manifests compatibly without forcing unrelated asset reimports. - Keep registry UUIDs and sub-asset IDs stable across metadata-only drift. ## Acceptance criteria - [x] A fresh LFS checkout remains clean after native editor startup, asset scan, `cargo validate-levels`, and `cargo validate-samples`. - [x] Touching an imported source without changing bytes produces no authored/generated diff. - [x] Changing bytes with the same length is detected and refreshes the correct manifests. - [x] Equivalent reimport output preserves exact file bytes, including formatting/newline. - [x] Static mesh, animation, texture, audio, and model-source paths share the deterministic policy. - [x] Tests cover mtime-only drift, same-size content change, old-manifest migration, and read-only validators. ## Docs/tests The content-addressed contract is owned by ADR 0043, integrated with ADRs 0017/0028, and enforced by the post-validator clean-worktree CI assertion. ## Evidence - [Acceptance results and exact commits](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/56#issuecomment-1102) - [Fresh-checkout native editor](https://git.spacetrainclubhouse.com/attachments/df761c85-0b82-4a25-9d33-9cf8189539f0) - [Imported model browser](https://git.spacetrainclubhouse.com/attachments/93da7803-de47-43fb-bb8c-f759970a2b5f) - [Versioned evaluation record](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/7e99243a78ee99207763ec92e80bcf6dd03f7151/docs/editor/evaluations/deterministic-asset-fingerprints/README.md)
blacksite-issue56-fresh-fixed-cbd380a.png
1.7 MiB
blacksite-issue56-models-e1b2f86.png
1.9 MiB
Rbanh added this to the M2 - Content workspace and asset pipeline milestone 2026-07-13 01:00:50 -04:00
Rbanh commented 2026-07-13 12:11:22 -04:00
Author
Owner
Copy Link

Acceptance complete

Published to main at 7e99243a78ee99207763ec92e80bcf6dd03f7151.

Implementation commits:

  • e1b2f86a495496da83947777d332d00a15a1779d - shared content-addressed fingerprints, registry/manifests, validators, CI cleanliness assertion, migration, tests, and ADR 0043.
  • cbd380a9413411667a83f74b66c5a2feda5e1af7 - normalized registry publication order plus discovery-order regression coverage.
  • 7e99243a78ee99207763ec92e80bcf6dd03f7151 - exact acceptance record, roadmap, debt audit, and production-readiness matrix 0.6.

Verification:

  • cargo fmt --all -- --check
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo test --workspace --all-targets --no-fail-fast (editor 300 passed; scene 100 passed plus one ignored manual migration; shared 99 passed; all workspace targets green)
  • cargo validate-levels --project . (81 dependencies, five known nonblocking findings, zero blocking)
  • cargo validate-samples --project . (five samples, 86 dependencies, the same five nonblocking findings, zero blocking)
  • Fresh detached LFS-hydrated checkout remained clean after native editor startup, asset scan, both validators, and process exit code 0.
  • Live mtime-only touch of RobotExpressive.glb produced no Git or generated-artifact diff; the original nanosecond timestamp was restored.
  • Registry plus all six committed static-mesh/animation artifacts retained their exact baseline SHA-256 values through every stage.
  • Same-size byte changes, legacy migration/timestamp tolerance, semantic byte preservation, imported source coverage, read-only validation, and reordered discovery are covered by regression tests.
  • Native editor and imported-model browser were visually inspected on Wayland.

Evidence:

Packaged acceptance remains explicitly owner-deferred and is not claimed. Native QA separately exposed missing external painted-chair FBX textures; that independent defect is tracked in #58. Production readiness remains Not ready under #50.

## Acceptance complete Published to `main` at `7e99243a78ee99207763ec92e80bcf6dd03f7151`. Implementation commits: - `e1b2f86a495496da83947777d332d00a15a1779d` - shared content-addressed fingerprints, registry/manifests, validators, CI cleanliness assertion, migration, tests, and ADR 0043. - `cbd380a9413411667a83f74b66c5a2feda5e1af7` - normalized registry publication order plus discovery-order regression coverage. - `7e99243a78ee99207763ec92e80bcf6dd03f7151` - exact acceptance record, roadmap, debt audit, and production-readiness matrix 0.6. Verification: - [x] `cargo fmt --all -- --check` - [x] `cargo clippy --workspace --all-targets -- -D warnings` - [x] `cargo test --workspace --all-targets --no-fail-fast` (editor 300 passed; scene 100 passed plus one ignored manual migration; shared 99 passed; all workspace targets green) - [x] `cargo validate-levels --project .` (81 dependencies, five known nonblocking findings, zero blocking) - [x] `cargo validate-samples --project .` (five samples, 86 dependencies, the same five nonblocking findings, zero blocking) - [x] Fresh detached LFS-hydrated checkout remained clean after native editor startup, asset scan, both validators, and process exit code 0. - [x] Live mtime-only `touch` of `RobotExpressive.glb` produced no Git or generated-artifact diff; the original nanosecond timestamp was restored. - [x] Registry plus all six committed static-mesh/animation artifacts retained their exact baseline SHA-256 values through every stage. - [x] Same-size byte changes, legacy migration/timestamp tolerance, semantic byte preservation, imported source coverage, read-only validation, and reordered discovery are covered by regression tests. - [x] Native editor and imported-model browser were visually inspected on Wayland. Evidence: - [Fresh-checkout native editor](https://git.spacetrainclubhouse.com/attachments/df761c85-0b82-4a25-9d33-9cf8189539f0) - [Imported models and FBX details](https://git.spacetrainclubhouse.com/attachments/93da7803-de47-43fb-bb8c-f759970a2b5f) - [`docs/editor/evaluations/deterministic-asset-fingerprints/`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/7e99243a78ee99207763ec92e80bcf6dd03f7151/docs/editor/evaluations/deterministic-asset-fingerprints/README.md) Packaged acceptance remains explicitly owner-deferred and is not claimed. Native QA separately exposed missing external painted-chair FBX textures; that independent defect is tracked in #58. Production readiness remains **Not ready** under #50.
Rbanh added reference main 2026-07-13 12:11:34 -04:00
Rbanh closed this issue 2026-07-13 12:11:36 -04:00
Rbanh changed reference from main to main 2026-07-13 12:12:02 -04:00
Rbanh changed reference from main to main 2026-07-13 12:12:19 -04:00
Sign in to join this conversation.
main
Branches Tags
Labels
Clear labels   
area:animation

Skeletal animation import, preview, graph/state authoring, and runtime integration.

  
area:assets

Asset browser, material browser, thumbnails, import, processing, and asset watcher.

  
area:audio

Audio source/listener authoring, buses, spatial preview, and runtime integration.

  
area:brushes

Brush geometry, CSG, face editing, UVs, and brush diagnostics.

  
area:build-release

Build profiles, packaging, content validation, release gates, and distribution diagnostics.

  
area:extensions

Static extension API, extension scaffolds, dylib exploration.

  
area:governance

Policy, attribution, planning, and production process.

  
area:hierarchy

Outliner hierarchy, parenting, grouping, prefab structure, ordering, and selection workflows.

  
area:inspector

Inspector, component metadata, component editing UX.

  
area:navigation

Navigation mesh authoring, baking, diagnostics, and AI path preview.

  
area:operators

Editor operator/action framework, undo, commit/cancel semantics.

  
area:physics

Physics placement, colliders, rigid bodies, diagnostics, and overlays.

  
area:project-ux

Project launcher, profiles, templates, or first-run project workflow.

  
area:quality

Regression packs, tests, performance budgets, profiler, first-hour UX.

  
area:rendering

Static and skinned renderers, material slots, shaders, ray tracing, and render-path integration.

  
area:runtime

BRP, remote inspector, PIE, game preview, runtime integration.

  
area:scene-io

Scene document, save/load, schema, migration, or reference repair.

  
area:terrain

Terrain authoring, terrain sculpting, heightmaps, and terrain materials.

  
area:viewport

Viewport interaction, selection, shortcuts, camera, overlays, and controls.

  
priority:P0

Must-have prerequisite or milestone-critical item.

  
priority:P1

Important production feature after P0 work is stable.

  
priority:P2

Useful follow-up or polish item.

  
priority:P3

Exploratory or later spike.

  
roadmap:jackdaw

Jackdaw-inspired Blacksite editor roadmap item.

  
roadmap:production

Blacksite production-readiness roadmap item beyond the Jackdaw-inspired foundation.

  
type:architecture

Architecture, internal framework, or hard-to-reverse technical decision.

  
type:docs

Documentation, policy, samples, or issue-board structure.

  
type:epic

Tracking epic that groups related milestone work.

  
type:feature

User-visible feature or capability.

No Label
area:animation
area:assets
area:audio
area:brushes
area:build-release
area:extensions
area:governance
area:hierarchy
area:inspector
area:navigation
area:operators
area:physics
area:project-ux
area:quality
area:rendering
area:runtime
area:scene-io
area:terrain
area:viewport
priority:P0
priority:P1
priority:P2
priority:P3
roadmap:jackdaw
roadmap:production
type:architecture
type:docs
type:epic
type:feature
Milestone
Clear milestone
No items
No Milestone
M2 - Content workspace and asset pipeline
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: Falling-Metal-Interactive/Blacksite#56
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?