---
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`.