44 lines
1.7 KiB
Markdown
44 lines
1.7 KiB
Markdown
---
|
|
id: LSN-0010
|
|
ticket: packer-docs-import
|
|
title: Asset identity and runtime contract legacy lesson
|
|
created: 2026-03-26
|
|
tags:
|
|
- 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`.
|