prometeu-studio/discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md

id	ticket	title	created	tags
LSN-0010	packer-docs-import	Asset identity and runtime contract legacy lesson	2026-03-26	packer legacy-import asset-identity runtime-contract

Context

Legacy import from docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md.

This lesson preserves the distinction between stable artifact identity and logical naming.

Key Decisions

asset_id and asset_name are intentionally different

What: asset_id is the stable artifact identity used for runtime-facing stability and preload integrity, while asset_name remains a logical, human-facing, code-facing reference. Why: Using only asset_name makes rename behave like identity breakage, while using only asset_id everywhere today makes source-level ergonomics worse. The architecture intentionally keeps both. Trade-offs: Carrying both values increases conceptual surface area, but it avoids forcing authoring ergonomics and stable runtime identity into one compromised field.

Patterns and Algorithms

• Use asset_id when the question is stable artifact identity.
• Use asset_name when the question is authoring/reference ergonomics.
• Keep both values visible in runtime-facing asset tables.

Pitfalls

• Treating rename as identity change.
• Treating name-only references as stable preload/bootstrap identity.
• Forcing code-facing APIs into raw integer identity too early.

Takeaways

• Stable identity and logical naming solve different problems.
• Runtime artifact correctness should prefer asset_id; human-facing and source-facing flows may still use asset_name.
• Legacy source attribution: docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md.