Fixture symbol resource contract

The GDTF symbol ownership and mutation contract defines the product and architecture policy. Core owns inspection, resolution, serialization, mutation, and project-symbol persistence. GUI code requests operations and presents previews and diagnostics.

Independent resource sets and owners

Resource set	Physical owner	Views
Standard GDTF	GDTF model resources	GDTF 1.2 Top: models/svg/<Model.File>.svg; Side: models/svg_side/<Model.File>.svg; Front: models/svg_front/<Model.File>.svg.
Internal Perastage	PSTG project resources under resources/fixture_symbols/ and project/session state before Save	Top, Front, Side, and Bottom, with Perastage rendering metadata.
Legacy internal Perastage	Historical GDTF resources, read-only compatibility input	Recognized perastage/symbols/ entries, Bottom extensions, and positively identified generated resources in official SVG locations.

Standard and internal completeness remain independent. GDTF 1.2 has no standard Bottom view. A missing or malformed internal Bottom cannot invalidate usable standard Top/Side/Front resources. The renderer represents Side with SymbolViewKind::Left and Right; Side compatibility is not a different-view fallback. Inspection records existence and usability independently, so an existing unusable resource is distinguishable from a missing resource.

core/symbols/gdtf_model_svg_inspection.* owns the per-Model presentation catalog. It retains Name, exact File, dimensions in meters, PrimitiveType, Geometry references, version-specific view descriptors, exact paths, offsets, presence and diagnostic state. Missing File is never invented; shared File values remain inspectable but carry an ambiguity diagnostic. This reader uses the shared archive boundary. The older single-model resource contract is retained for runtime/legacy rendering compatibility, not authoring or Model presentation. Reading a GDTF never rewrites the source. Individual partial resources remain available even when their resource set is incomplete. Resource-set membership and provenance are separate: standard output generated by Perastage remains a standard resource, while a project symbol remains project-owned.

Project persistence and manual Apply

Generated fallback symbols and explicit user overrides are project data. Manual Apply views to fixture stores a UserOverride bundle and binds all fixture instances sharing the exact definition reference and mode. Names alone do not select bindings. Apply does not inject private symbols into a GDTF, require an owned library derivative, or invent a project base path. An unsaved scene retains the symbol in project/session state until Save. A newly inserted fixture inherits a stored representation only when existing bindings for the same nonempty exact source reference and mode agree on one content identity. Divergent overrides remain unchanged and produce an inheritance diagnostic; empty references do not bind unrelated fixtures.

core/symbols/project_fixture_symbols.* owns schema version 1, persistence, content identity, and explicit bindings. Additional resources use ProjectSession::ArchiveResource outside scene.mvr:

resources/fixture_symbols/
  index.json
  <sha256-64-lowercase-hex-digest>/
    manifest.json
    top.svg
    front.svg
    side.svg
    bottom.svg

Content IDs use sha256- followed by 64 lowercase hexadecimal digits. index.json contains schema_version, fixture_bindings (canonical fixture UUID to definition ID), and definitions (definition ID to bundle content ID). A bundle manifest contains schema_version, generator_version, kind (generated_fallback or user_override), source_fixture_type_id, source_fingerprint, and views. Each view records view, file, offset_x_mm, and offset_y_mm, plus optional source_archive_path and source_provenance for migrated legacy/authored presentation snapshots. The content hash includes exact SVG bytes and complete manifest metadata, so identical bundles share packaged payloads. Generated/manual bundles require the four current views. Legacy migration preserves positively identified internal views and can snapshot complementary authored views needed to reproduce their resolved rendering. Per-view source provenance distinguishes those authored bytes without claiming them as generated. Partial bundles retain only available views; absent views are not invented and only present view files are packaged. Definition IDs include the sorted bound UUID scope and bundle content ID, making revisions immutable for untouched cloned fixtures and Undo snapshots. Payload deduplication remains independent from definition scope. Only scene-referenced bundles are packaged; successful Save/Apply prunes orphaned state rather than accumulating resources indefinitely.

Load restores exact bytes and UUID bindings without requiring the original external GDTF, a fixture filename, or a cache. A generator-version change alone never regenerates a stored representation. User overrides are authoritative. Malformed indices, missing/corrupt bundles, or a content-hash mismatch reject project loading before scene/config callbacks, preserving the active project and preventing partial state or silent override replacement. Later binding or scene/config callback failures restore the active scene, symbol store, extracted resources, layouts, and preferences through the load transaction. A PSTG without a symbol index retains the normal standard/legacy/geometry fallback.

Resolution and previews

fixture_symbol_resolution.* owns per-view GDTF candidate policy without parsing archives or depending on GUI types. Internal rendering first resolves the explicitly bound project resource, then uses read-only legacy compatibility, standard resources, or the established view/geometry fallback. A saved project resource takes precedence over runtime generation or disposable caches.

FixtureSymbolResolutionPurpose::StandardGdtf resolves standard resources only. Project and legacy internal content does not become a standard resource merely because it renders the same view; legacy fallback is restricted to internal rendering. Bottom has no standard candidate. Internal Right resolves Side while keeping the requested rendering orientation; Back retains the existing Top fallback.

fixture_symbol_availability.* is the shared loading boundary for renderers, layout, legends, PDF, previews, and preparation. Completeness describes exact stored views, not mixed fallback results. Resolutions retain requested/actual view, resource set, provenance, path, offsets, fallback reason, and diagnostics. The SVG cache caches immutable parsed data and does not own candidate policy. Captured explicit source paths and project tokens remain authoritative in layout lookups; old name-only captures can resolve GDTF compatibility sources but names never select a project override.

Background PDF export copies the project symbol store on its owning GUI thread and uses ScopedProjectFixtureSymbolReadContext around the export worker. Build/inspection/loading then resolve against that immutable snapshot. Replacing the active project, applying an override, or clearing the parsed cache cannot change the export already in progress. The scoped context does not serialize data or become another project owner.

Live layout frame identity includes the authoritative project source token. Apply and Undo/Redo invalidate layout render content. Saved layout-cache validation includes referenced project-symbol index/manifest/SVG bytes alongside layout images in the existing named-resource fingerprint; unchanged scene.mvr alone cannot prove that a stored rendering still matches its symbols.

The Fixture Editor uses a compact Model selector for exact authored Standard GDTF views through the general SVG bitmap backend, with resource presence separate from preview support. It never uses another Model or view as an original. The independent Perastage project (PSTG) group shows fixture-wide Top/Front/Side/Bottom; user overrides have distinct provenance. Its original-resource previews accept only a usable resource in the requested group and logical view; a Top or other-group fallback is not presented as an original. Missing and unusable views retain their diagnostics. A recognized legacy Perastage marker at an official Model path is reported as present legacy input, and never impersonates an authored Model original. Standard Bottom remains unavailable.

Separate SVG output targets

core/symbols/Symbol2DSvg.* owns the pure vector serialization primitives. The project-symbol output retains Perastage metadata and independent offsets needed to reproduce rendering. standard_gdtf_svg.* owns standard output with its own validation: physical dimensions in millimeters, no data-perastage-* markers or private ownership metadata, no Bottom, and GDTF-version resource paths.

Both outputs preserve the existing polygon-with-holes geometry. A region with drawable holes becomes one SVG 1.1 compound path with fill-rule="evenodd"; hole-free regions retain polygon output. Holes expose the actual background. The deterministic parser and historical white-hole recovery remain available for positively recognized legacy content. GUI exporters own file-output wrappers.

Standard mutation boundary

Automatic preparation produces PSTG Top/Front/Side/Bottom only, under either historical mutation-policy value. Missing standard SVGs do not schedule capture when the project representation is valid. No capture calls the dormant standard completion boundary or creates a derivative, changes Model offsets or rebinds GDTF references. Source archive bytes remain identical.

standard_gdtf_completion.* retains canonical serialization/publication for future model-local operations. It requires an explicit exact nonempty Model/@File, rejects duplicates, and never chooses Main or a first Model. An existing readable resource is preserved regardless of internal polygon parser support. Explicit repair/replacement requires its separate intent API; there is no new repair GUI. Effective intentional mutations use the existing canonical owned derivative and standard Revision boundary.

The automatic completion Preferences control is removed. Historical settings still parse; no settings migration is required. Explicit physical-property editing remains available.

Legacy compatibility

Legacy perastage/symbols/<model>/, models/svg/<model>_bottom.svg, and models/svg_bottom/<model>.svg remain readable. Unmarked historical Bottom content can be displayed as an internal compatibility input but is not claimed as generated or migrated without positive ownership evidence. Version/ownership markers and exact historical fixture-symbol revision evidence identify compatible generated resources. Generic editor values, unrelated revisions, audit nodes, and model names such as base or main do not establish resource ownership.

New writes never create these private GDTF outputs. A positively identified legacy symbol is materialized into project-owned PSTG storage on Save, before legacy GDTF reference consolidation, without rewriting the external GDTF merely because it was opened. An unchanged legacy GDTF can remain embedded under the existing MVR preservation policy; this compatibility input is distinct from newly generated private output. Intentional derived publication sanitizes positively recognized legacy output and records effective cleanup through standard revisions. Unknown authored resources are never claimed as Perastage-owned. Historical overwritten manufacturer bytes cannot be reconstructed without an authoritative original; affected libraries should be rebuilt from clean sources where practical.

Legacy marker support does not authorize adding markers to new standard SVGs. Later exact standard replacement revisions supersede older legacy evidence for the affected views. Audited publication cleanup supersedes that evidence at official paths, while surviving SVG ownership markers remain legacy input. Unknown unsupported Bottom resources require explicit repair before publication; their original bytes are preserved. An exact standard Model/@File containing _bottom still identifies an ordinary standard view and is retained. Provenance for new GDTF output belongs in standard revisions and project metadata. Semantic fingerprints retain symbol-relevant standard and legacy resource inputs; hot parsed-SVG cache lookups remain bounded and do not hash whole archives.