prometeu-studio/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md

id	ticket	title	status	created	completed	tags
PLN-0005	pbs-game-facing-asset-refs-and-call-result-discard	Propagate DEC-0005 Asset Address Surface into Compiler, Packer, and Studio Specs	done	2026-03-27	2026-03-27	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.