153 lines
6.8 KiB
Markdown
153 lines
6.8 KiB
Markdown
---
|
|
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.
|