---
id: LSN-0009
ticket: packer-docs-import
title: Packer mental model legacy lesson
created: 2026-03-26
tags:
  - packer
  - legacy-import
  - mental-model
---

## Context

Legacy import from `docs/packer/learn/mental-model-packer.md`.

This lesson preserves the high-level didactic framing of what the packer is and is not.

## Key Decisions

### The packer turns asset workspaces into stable asset artifacts

**What:** The packer is neither cartridge shipper, runtime reader, nor generic file janitor. It is the system that turns a managed asset workspace into stable runtime-facing and tool-facing artifacts.
**Why:** Contributors drift quickly when they treat packer behavior as a mix of authoring convenience, runtime semantics, and shipping responsibilities rather than one explicit artifact-producing domain.
**Trade-offs:** This framing forces sharper boundaries between packer, runtime, shipper, and Studio, but it keeps contracts and responsibilities legible.

## Patterns and Algorithms

- Treat the managed asset root as the unit of management.
- Split source-of-truth responsibilities between registry state and per-asset declaration.
- Keep `asset_id` and `asset_name` as separate concepts.
- Treat `assets.pa` as the authoritative runtime-facing artifact.
- Prefer determinism, explicit declaration, and canonical serialization.

## Pitfalls

- Treating the packer like a generic filesystem janitor.
- Collapsing `asset_id` and `asset_name` into one concept.
- Forgetting that determinism is part of the artifact contract chain.

## Takeaways

- The packer owns artifact production, not runtime reading or shipping.
- Stable asset identity and deterministic output are central to the whole domain.
- Legacy source attribution: `docs/packer/learn/mental-model-packer.md`.