---
id: PLN-0005
ticket: pbs-game-facing-asset-refs-and-call-result-discard
title: Propagate DEC-0005 Asset Address Surface into Compiler, Packer, and Studio Specs
status: review
created: 2026-03-27
completed:
tags: [compiler, pbs, packer, studio, specs, addressable, asset-identity, be-fe-contract]
---

## Objective

Propagate `DEC-0005` into the normative documentation so PBS asset authoring, backend-owned `FESurfaceContext`, and the separation between `asset` and `bank` become explicit, cross-domain, and implementation-ready.

## Background

`DEC-0005` locks the symbolic authoring surface for assets around:

- hierarchical `assets...` addressing;
- `Addressable` as the public/editorial PBS type shape;
- `FESurfaceContext` as a backend-owned contract delivered to the frontend;
- `List<Addressable(address, asset_id)>` as the v1 asset slice;
- backend-owned validation and lowering from symbolic address to runtime-facing `asset_id`;
- explicit separation between asset references and bank-internal addressing.

The repository already documents:

- packer ownership of `asset_id`;
- Studio ownership of asset workspace UX;
- PBS low-level runtime asset access through `LowAssets`.

What is still missing is the normative bridge between these surfaces.

## Scope

### Included
- Update PBS language specs to define the symbolic asset address model and the backend-to-frontend contract.
- Update packer specs to state how the operational snapshot projects canonical asset addresses without turning `asset_name` into a first-class operational identity.
- Update Studio specs to state that UI-facing asset identity aligns with the canonical address surface and namespace collision rules.
- Add or update compiler-level specs so backend-owned asset lowering and `FESurfaceContext` ownership are normatively visible.

### Excluded
- Implementing parser, semantic, lowering, or diagnostics code.
- Designing bank-internal member addressing.
- Defining richer future `FESurfaceContext` slices beyond assets.
- Introducing rename-fragility warnings or LSP-only UX refinements.

## Execution Steps

### Step 1 - Update PBS Normative Surface Documents

**What:**
Document the symbolic PBS surface for asset references and the `Addressable` model.

**How:**
Revise the PBS specs so they state:

- `assets` is a compile-time namespace root;
- leaves correspond to terminal `Addressable` values;
- the canonical symbolic identity is the normalized asset-root-derived address;
- `asset_name` is not the operational compile-time identity;
- the PBS frontend may use a fake/editorial `Addressable` type while the backend remains the owner of executable semantics.

**File(s):**
- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`
- `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`
- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`

### Step 2 - Update Backend Contract and Lowering Specs

**What:**
Make the backend-owned `FESurfaceContext` and asset-lowering ownership explicit in compiler-wide specs.

**How:**
Add or revise sections that state:

- the frontend receives a minimal backend-derived surface, not the raw packer snapshot;
- v1 assets arrive as `List<Addressable(address, asset_id)>`;
- backend validation and final lowering ownership remain backend-only;
- symbolic asset references lower into the already-accepted `LowAssets` contract before runtime execution.

**File(s):**
- `docs/specs/compiler/18. Standard Library Surface Specification.md`
- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
- optional conformance/matrix sync if needed: `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`

### Step 3 - Update Packer And Studio Domain Specs

**What:**
Align packer and Studio domain specs with the symbolic address model and namespace rules.

**How:**
Revise the specs so they state:

- packer remains owner of operational asset identity and derives canonical addresses from asset roots;
- `asset_name` is not required as an operational registry field;
- Studio should expose canonical address identity in UX where appropriate;
- Studio must prevent terminal-vs-namespace collisions on asset root creation and moves.

**File(s):**
- `docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md`
- `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md`
- `docs/specs/studio/4. Assets Workspace Specification.md`

### Step 4 - Cross-Check Decision Boundaries

**What:**
Verify that the edited specs preserve the intended scope split between `DEC-0004`, `DEC-0005`, and bank-specific addressing.

**How:**
Check that:

- `DEC-0004` still owns only the low-level `LowAssets` ABI;
- `DEC-0005` owns the symbolic authoring and backend-owned surface contract;
- no updated document accidentally defines bank-internal member addressing or future richer `FESurfaceContext` slices.

**File(s):**
- `discussion/workflow/decisions/DEC-0004-pbs-low-level-asset-manager-surface.md` if restored for reference, otherwise use `discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md`
- `discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md`

## Test Requirements

### Unit Tests
- None required for the editorial plan itself.

### Integration Tests
- None required for the editorial plan itself.

### Manual Verification
- Read updated specs together and verify the same terminology is used for `Addressable`, canonical address, `asset_id`, and `FESurfaceContext`.
- Verify no document reintroduces `asset_name` as the normative compile-time identity.
- Verify no document collapses `asset` references with bank-internal addressing.

## Acceptance Criteria

- [ ] PBS specs describe hierarchical asset addressing and `Addressable` as the symbolic authoring surface.
- [ ] Compiler specs state that the backend exposes a minimal `FESurfaceContext` and retains final validation/lowering ownership.
- [ ] Packer specs state that canonical asset addresses are derived operationally without promoting `asset_name` back to first-class identity.
- [ ] Studio specs state the namespace-collision rule for asset root creation and moves.
- [ ] Updated docs preserve the scope boundary between low-level `LowAssets` ABI and symbolic asset references.

## Dependencies

- `DEC-0005-pbs-asset-address-surface-and-be-lowering`
- Existing `DEC-0004` low-level `LowAssets` contract

## Risks

- Cross-domain wording may drift if compiler, packer, and Studio specs are updated independently.
- Over-documenting future `FESurfaceContext` expansion now would make the contract harder to keep stable.
- It is easy to accidentally reintroduce `asset_name` as an editorial convenience unless the operational/authoring distinction stays explicit.