# Asset Identity and Runtime Contract

This document explains the point that is easiest to get subtly wrong:

- `asset_id` is the stable artifact identity;
- `asset_name` is still a logical code-facing reference.

If you flatten those two concepts into one, the architecture starts drifting immediately.

## The Stable Side: `asset_id`

`asset_id` is allocated by the packer registry.

It is stable within the project and appears in runtime-facing artifacts.

Why this matters:

- preload uses `asset_id`;
- artifact identity survives move and rename;
- build outputs remain structurally stable even when authoring layout changes.

`asset_id` is the answer to:

> “Is this the same asset as before?”

## The Logical Side: `asset_name`

`asset_name` remains useful because game-facing code and runtime APIs still refer to assets by name in normal flows.

Why this matters:

- authors need a readable label;
- game code usually references assets semantically, not by integer literal;
- runtime lookup still uses names in parts of the current operational surface.

`asset_name` is the answer to:

> “What do humans and source code call this asset?”

## Why Not Use Only One Of Them?

If you use only `asset_name`:

- rename becomes identity breakage;
- preload/bootstrap integrity becomes fragile;
- build artifacts depend too much on mutable author intent.

If you use only `asset_id` everywhere today:

- source code becomes less ergonomic;
- authoring workflows become harder to read;
- the current runtime/game-facing API model would need stronger compile-time lowering infrastructure.

So the current architecture intentionally keeps both:

- stable identity for artifacts;
- logical naming for authoring and API usage.

## What Actually Happens In The Artifact?

The runtime-facing asset table carries both:

- `asset_id`
- `asset_name`

But they play different roles.

`asset_id`:

- defines stable identity;
- is used for preload/bootstrap integrity.

`asset_name`:

- stays in the table as descriptive/API-facing metadata;
- supports name-based lookup where that still exists.

## Why This Is Still Not The End Of The Story

There is still an open language/toolchain question:

- should source-level asset references remain name-based forever?
- or should the compiler eventually lower known references to stable IDs or resource handles?

That is a separate problem from the packer artifact identity model.
It belongs to language/frontend and runtime API design, not to the core packer identity rules.

## Practical Rule

When reading or implementing packer behavior, use this checklist:

- if the question is about stable artifact identity, think `asset_id`;
- if the question is about source naming or human-facing lookup, think `asset_name`;
- if the question is about preload/bootstrap correctness, prefer `asset_id`;
- if the question is about runtime/game API ergonomics, `asset_name` may still be intentionally present.