discussion framework migration
This commit is contained in:
@@ -0,0 +1,8 @@
|
||||
{"type":"meta","next_id":{"DSC":8,"AGD":8,"DEC":4,"PLN":4,"LSN":23,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
---
|
||||
id: LSN-0001
|
||||
ticket: studio-docs-import
|
||||
title: Assets workspace execution wave legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- studio
|
||||
- legacy-import
|
||||
- assets-workspace
|
||||
- event-driven-ui
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/studio/learn/assets-workspace-execution-wave.md`.
|
||||
|
||||
This lesson captures the didactic consolidation of the first `Assets` workspace execution wave after the original implementation slices had already been absorbed into Studio specs and learn material.
|
||||
|
||||
Relevant specs:
|
||||
|
||||
- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md`
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md`
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Assets workspace should remain asset-first, event-driven, and preview-first
|
||||
|
||||
**What:** The stable workspace model treats `Assets` as a real asset workspace, separates navigator projection from details rendering, routes routine UI ownership through typed events, and keeps sensitive mutations preview-first rather than refresh-heavy or modal-first.
|
||||
**Why:** The original execution wave produced many local slices, but the enduring lesson is the ownership model: local redraws instead of workspace-wide refresh, didactic asset detail ordering, workspace-local review with shell-level lifecycle visibility, and semantically separate mutation feedback.
|
||||
**Trade-offs:** This model requires more deliberate component boundaries and event routing, but it avoids monolithic redraw logic and keeps the UI easier to reason about as the workspace grows.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Treat `Assets` as a real workspace with explicit `loading`, `empty`, `error`, and `ready` states.
|
||||
- Keep navigator updates and selected-asset details updates independently owned.
|
||||
- Use typed workspace events for local state flow instead of defaulting to `refresh()`.
|
||||
- Keep activity at shell scope, while review and mutation reasoning stay inside the workspace.
|
||||
- Reserve modal confirmation for high-risk commit boundaries; use inline preview as the default review surface.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating `Assets` like a filesystem explorer with extra badges.
|
||||
- Rebuilding navigator, details, and unrelated controls for row-scoped changes.
|
||||
- Letting details sections depend on one monolithic selected-asset redraw.
|
||||
- Using logs as the main explanation surface for mutations.
|
||||
- Publishing shell activity without keeping workspace-local review visible.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The durable lesson from the first `Assets` execution wave is the ownership model, not the historical sequencing of implementation slices.
|
||||
- Event-directed local redraw and preview-first mutation review are foundational Studio patterns for the asset workspace.
|
||||
- Legacy source attribution: `docs/studio/learn/assets-workspace-execution-wave.md`.
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
---
|
||||
id: LSN-0002
|
||||
ticket: studio-docs-import
|
||||
title: Bank composition editor legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- studio
|
||||
- legacy-import
|
||||
- bank-composition
|
||||
- staged-editing
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/studio/learn/bank-composition-editor.md`.
|
||||
|
||||
This lesson captures the first-wave `Bank Composition` model as a didactic Studio pattern inside `Asset Details`, with direct relevance to `docs/studio/specs/4. Assets Workspace Specification.md` and packer-facing integration boundaries.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Bank composition should use a Studio DTO boundary and staged session coordinator
|
||||
|
||||
**What:** `Bank Composition` should operate through Studio-owned DTOs, intentionally dumb visual components, one section-scoped coordinator built around `StudioFormSession<BankCompositionDraft>`, minimal public workspace-bus notifications, and a persistence path that goes through packer rather than direct Studio writes.
|
||||
**Why:** Direct binding to raw packer/runtime shapes, rule-heavy generic controls, and direct `asset.json` writes would collapse family-specific rules into the wrong layer and duplicate authority that belongs to packer.
|
||||
**Trade-offs:** The section needs a dedicated coordinator and DTO projection layer, but that cost keeps component boundaries honest and makes family-specific capacity and transfer semantics easier to control.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Keep `available` and `selected` state in Studio-owned DTOs rather than raw packer objects.
|
||||
- Land the section shell early and follow the existing staged-edit rhythm: `change`, `apply`, `reset`, `cancel`.
|
||||
- Keep `StudioDualListView<T>` and `StudioAssetCapacityMeter` state-driven rather than rule-driven.
|
||||
- Let the section-scoped coordinator own draft lifecycle, transfer/reorder effects, blockers, hints, and apply handling.
|
||||
- Submit ordered selected files to packer, then rebind from refreshed persisted state after apply.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Binding the section UI directly to raw snapshot rows or manifest shape.
|
||||
- Hiding bank-family rules inside the dual list or capacity meter.
|
||||
- Creating a second staged-edit model parallel to `StudioFormSession`.
|
||||
- Turning every local action into a public workspace-bus event.
|
||||
- Writing `asset.json` directly from Studio.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The lasting lesson is not the specific first-wave editor controls; it is the ownership boundary between projection, orchestration, dumb components, and packer persistence.
|
||||
- Section-scoped coordinators are the right place for family-specific editing semantics in Studio.
|
||||
- Legacy source attribution: `docs/studio/learn/bank-composition-editor.md`.
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
---
|
||||
id: LSN-0003
|
||||
ticket: studio-docs-import
|
||||
title: Asset mutations legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- studio
|
||||
- legacy-import
|
||||
- asset-mutations
|
||||
- preview-first
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/studio/learn/mental-model-asset-mutations.md`.
|
||||
|
||||
This lesson preserves the didactic rule for how Studio must present asset mutations in the `Assets` workspace, aligned with `docs/studio/specs/4. Assets Workspace Specification.md` and packer integration boundaries.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Sensitive asset mutations must be preview-first
|
||||
|
||||
**What:** Studio should treat destructive or relocational asset mutations as preview-first workflows, keep registry impact and workspace impact distinct, and reserve modal confirmation for high-risk final commits rather than using modals as a substitute for review.
|
||||
**Why:** Users lose trust quickly when the UI hides whether a mutation affects only registry state or also the physical workspace. Inline staged review keeps the user anchored in the selected asset and its consequences.
|
||||
**Trade-offs:** Inline review takes more UI structure than a modal-only flow, but it produces a clearer and safer operational model for both single-asset and batch mutations.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Show affected assets, scope of impact, creations/moves/deletions, blockers, warnings, and safe fixes before apply.
|
||||
- Use an inline staged panel as the default review surface.
|
||||
- Keep `blockers`, `warnings`, and `safe fixes` visually and semantically distinct.
|
||||
- For batch operations, show an aggregate summary first and drill-down detail second.
|
||||
- Reflect lifecycle milestones such as `preview ready`, `action applied`, and `action failed` at shell scope while keeping review inside the workspace.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Destructive apply without preview.
|
||||
- Using raw logs as the main explanation surface.
|
||||
- Mixing safe fixes with deletes as if they were the same class of action.
|
||||
- Showing technical diff data without user-facing interpretation.
|
||||
- Forcing modal-only review for ordinary mutation flows.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Preview is the review; modal confirmation is only the final safety gate for high-risk commits.
|
||||
- Registry impact and workspace impact must never blur in Studio mutation UX.
|
||||
- Legacy source attribution: `docs/studio/learn/mental-model-asset-mutations.md`.
|
||||
+51
@@ -0,0 +1,51 @@
|
||||
---
|
||||
id: LSN-0004
|
||||
ticket: studio-docs-import
|
||||
title: Assets workspace mental model legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- studio
|
||||
- legacy-import
|
||||
- assets-workspace
|
||||
- asset-first
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/studio/learn/mental-model-assets-workspace.md`.
|
||||
|
||||
This lesson keeps the didactic framing for the `Assets` workspace as an asset-first, path-aware Studio surface over the packer model.
|
||||
|
||||
Relevant specs:
|
||||
|
||||
- `docs/studio/specs/4. Assets Workspace Specification.md`
|
||||
- `docs/packer/learn/mental-model-packer.md`
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### The assets workspace exists to teach the asset model, not to act as a nicer file browser
|
||||
|
||||
**What:** The `Assets` workspace should treat asset identity as primary, path as supporting context, and the selected-asset view as a didactic explanation surface ordered around what the asset is, what it produces, what it contains, what is wrong, and what actions are available.
|
||||
**Why:** A raw file-tree framing teaches the wrong mental model for packer-backed assets. The Studio needs to make managed assets, runtime-facing output, previewable inputs, and operational state understandable from the UI itself.
|
||||
**Trade-offs:** Asset-first navigation requires custom navigator semantics and stronger didactic structure, but it produces a clearer and more accurate Studio view over the project.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Use a custom asset navigator rather than a generic file explorer.
|
||||
- Keep grouping/path visible as supporting context while preserving asset identity as primary.
|
||||
- Present the selected asset in a fixed teaching order: `Summary`, `Runtime Contract`, `Inputs / Preview`, `Diagnostics`, `Actions`.
|
||||
- Treat preview as part of the bridge between the conceptual asset model and real project materials.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Turning the workspace into a filesystem explorer with badges.
|
||||
- Making path the true identity instead of the asset.
|
||||
- Showing only diagnostics and forgetting the asset model itself.
|
||||
- Treating orphan as equivalent to broken.
|
||||
- Hiding runtime-facing information behind technical dumps.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The key durable rule is `asset-first`, not `file-first`.
|
||||
- Path-awareness is supporting context, not the primary identity model.
|
||||
- Legacy source attribution: `docs/studio/learn/mental-model-assets-workspace.md`.
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
---
|
||||
id: LSN-0005
|
||||
ticket: studio-docs-import
|
||||
title: Studio events and components legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- studio
|
||||
- legacy-import
|
||||
- events
|
||||
- components
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/studio/learn/mental-model-studio-events-and-components.md`.
|
||||
|
||||
This lesson preserves the Studio-wide mental model for typed events and the `prometeu-studio-components` control layer.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Studio should grow through typed events and a Studio-owned control layer
|
||||
|
||||
**What:** The Studio should use a typed event model with both workspace buses and a global bus, automatically republishing workspace events upward, while visible controls should come through `prometeu-studio-components` rather than raw JavaFX usage scattered across the app.
|
||||
**Why:** Direct references between shell, workspaces, and services create coupling that becomes hard to unwind as the application gains global activity, background operations, multiple workspaces, and cross-cutting actions. Raw JavaFX use also causes naming, styling, and behavior drift.
|
||||
**Trade-offs:** This approach adds explicit control layers and event publication paths, but it keeps the UI dialect smaller, more opinionated, and easier to evolve consistently.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Give each workspace its own bus and republish workspace events to the global Studio bus.
|
||||
- Keep event publication explicit and typed.
|
||||
- Use `prometeu-studio-components` as the Studio-facing control API rather than reimplementing JavaFX wholesale.
|
||||
- When adding UI code, ask whether the behavior is an event and whether the control is part of the Studio-visible dialect.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Letting shell, workspaces, and services call each other directly by convenience.
|
||||
- Spreading raw JavaFX controls directly across the app.
|
||||
- Recreating local wrappers and styling hooks inconsistently.
|
||||
- Treating the component layer as a full JavaFX replacement instead of a focused Studio API.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Typed events and a Studio-owned control layer solve different problems, but together they prevent architectural drift as the UI grows.
|
||||
- Workspace-local segregation and global shell visibility both matter; one bus alone is not enough.
|
||||
- Legacy source attribution: `docs/studio/learn/mental-model-studio-events-and-components.md`.
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
---
|
||||
id: LSN-0006
|
||||
ticket: studio-docs-import
|
||||
title: Studio shell mental model legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- studio
|
||||
- legacy-import
|
||||
- shell
|
||||
- workspace-boundary
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/studio/learn/mental-model-studio-shell.md`.
|
||||
|
||||
This lesson preserves the Studio-wide boundary between shell framing concerns and workspace operational detail.
|
||||
|
||||
Relevant spec:
|
||||
|
||||
- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md`
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### The shell should frame workspaces without absorbing their operational detail
|
||||
|
||||
**What:** The Studio shell owns project entry, global menus, fixed workspace navigation, the workspace host, right-side utility surface, and always-visible run control, while each workspace owns its own main body and domain-specific operational detail.
|
||||
**Why:** Early JavaFX apps often collapse into one giant frame where every new concern lands at shell scope. The chosen shell model avoids that drift and keeps topology stable without prematurely committing to a fully docked IDE model.
|
||||
**Trade-offs:** A structured shell limits early flexibility compared with full docking, but it prevents the codebase from solving layout-persistence and docking complexity before the product actually needs it.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Keep shell concerns focused on framing, not workspace internals.
|
||||
- Keep operational detail such as asset-management views, debugger/profiler content, and workspace-local logs inside the relevant workspace.
|
||||
- Treat `Run` as a persistent shell control because it is a primary action rather than a secondary panel.
|
||||
- Use the practical rule: framing concerns go to the shell; workspace operational detail stays in the workspace.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Adding every new concern to one giant shell layout.
|
||||
- Treating shell-wide console surfaces as mandatory for all detailed logs.
|
||||
- Introducing docking complexity before the product topology is proven.
|
||||
- Hiding primary actions like `Run` behind avoidable navigation friction.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The shell frames workspaces; it does not absorb them.
|
||||
- The shell/workspace boundary is a product rule, not just a layout preference.
|
||||
- Legacy source attribution: `docs/studio/learn/mental-model-studio-shell.md`.
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
id: LSN-0007
|
||||
ticket: studio-docs-import
|
||||
title: Pack wizard shell legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- studio
|
||||
- legacy-import
|
||||
- pack-wizard
|
||||
- packer-boundary
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/studio/learn/pack-wizard-shell.md`.
|
||||
|
||||
This lesson keeps the first-wave Studio rule for the `Pack` wizard as a shell over packer-owned operations, aligned with `docs/studio/specs/4. Assets Workspace Specification.md` and packer integration docs.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Pack should be a Studio-owned wizard shell over packer-owned operations
|
||||
|
||||
**What:** The `Pack` flow should be a phase-based wizard with `Summary`, `Validation`, `Packing`, and `Result`, where Studio owns presentation and state binding while packer owns build-set summary, validation, execution, progress, and result semantics.
|
||||
**Why:** A plausible-looking Studio modal can quietly reimplement packer semantics or hide operational phases. The wizard should expose those phases without pretending Studio owns build execution.
|
||||
**Trade-offs:** The wizard structure is more explicit than one opaque modal state, but it keeps operational ownership honest and makes blocked, failed, and successful outcomes easier to reason about.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Treat `Pack` as a workspace-level action over the current build set, not a selected-asset action.
|
||||
- Ask packer for the build-set summary instead of recomputing it locally from navigator state.
|
||||
- Use a separate validation phase that runs only on `registered + included in build`.
|
||||
- Reflect packer-owned progress honestly and keep the first wave non-cancelable if packer does not support cancel.
|
||||
- Make `assets.pa` the primary runtime artifact in the result summary; companion artifacts remain supporting detail.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating pack summary as a local Studio recomputation.
|
||||
- Using one opaque modal state instead of explicit operational phases.
|
||||
- Letting unrelated assets influence wizard validation.
|
||||
- Exposing fake cancel behavior unsupported by packer.
|
||||
- Making companion artifacts dominate the main result summary.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The important lasting rule is ownership: Studio shells the flow, packer owns the semantics.
|
||||
- Explicit phases are a didactic and operational feature, not decorative UI ceremony.
|
||||
- Legacy source attribution: `docs/studio/learn/pack-wizard-shell.md`.
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
---
|
||||
id: LSN-0008
|
||||
ticket: studio-docs-import
|
||||
title: Project-scoped state and activity legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- studio
|
||||
- legacy-import
|
||||
- project-state
|
||||
- activity
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/studio/learn/project-scoped-state-and-activity.md`.
|
||||
|
||||
This lesson preserves the rule for project-local Studio state and shell activity persistence.
|
||||
|
||||
Relevant spec:
|
||||
|
||||
- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md`
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Project-local Studio state should live under `.studio/` inside the project root
|
||||
|
||||
**What:** Project-local Studio state should be rooted at `.studio/`, shell activity should be persisted and restored per project, persisted history should be bounded, and `.studio/` should remain the reserved root for future project-local Studio settings.
|
||||
**Why:** If project-local state is stored as if it were application-global, the shell mixes unrelated histories and stops teaching what happened in the currently opened project.
|
||||
**Trade-offs:** This design requires project-scoped persistence logic and bounded retention, but it preserves causality and keeps Studio-owned project data in one obvious root.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Create `.studio/` during new-project scaffolding.
|
||||
- Load shell activity when the project opens.
|
||||
- Append new activity to the current project's local history.
|
||||
- Trim persisted activity to the latest `500` entries.
|
||||
- Keep launcher-global concerns outside the project-local `.studio/` root.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating project activity as launcher-global state.
|
||||
- Mixing multiple projects into one persisted activity history.
|
||||
- Leaving project-local Studio files in ad hoc roots instead of `.studio/`.
|
||||
- Allowing activity persistence to grow without a hard cap.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Project-local history must preserve causality for the currently opened project.
|
||||
- `.studio/` is the reserved home for project-scoped Studio state.
|
||||
- Legacy source attribution: `docs/studio/learn/project-scoped-state-and-activity.md`.
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
id: LSN-0016
|
||||
ticket: studio-docs-import
|
||||
title: Studio docs import pattern
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- studio
|
||||
- migration
|
||||
- discussion-framework
|
||||
- import-pattern
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
This lesson summarizes the completed migration of `docs/studio` into `discussion/`.
|
||||
|
||||
The original migration control artifacts were:
|
||||
|
||||
- `AGD-0001`
|
||||
- `DEC-0001`
|
||||
- `PLN-0001`
|
||||
|
||||
Those workflow files are being deleted during housekeeping. The index remains the permanent historical record.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Domain documentation import should preserve retained truth instead of reconstructing deleted history
|
||||
|
||||
**What:** The `docs/studio` migration imported only retained artifacts, rewrote them into framework-native templates, turned retained `learn` documents into legacy lessons, kept `specs` outside `discussion/`, and promoted imported open agendas into their own new discussions.
|
||||
**Why:** Reconstructing deleted decisions or plans would fabricate workflow history. The retained source set already contained the truth that mattered: one open agenda, zero retained decisions, zero retained plans, and a didactic learn corpus.
|
||||
**Trade-offs:** This approach requires explicit editorial normalization and separate migration bookkeeping, but it yields a canonical framework surface without inventing missing history.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Import only currently retained domain artifacts.
|
||||
- Rewrite imported material into native framework templates.
|
||||
- Turn retained `learn` material into legacy lessons under the migration discussion directory.
|
||||
- Split retained open agendas into new discussions rather than leaving them nested inside the migration discussion.
|
||||
- Keep `specs` as external normative references.
|
||||
- Use housekeeping to delete completed migration control artifacts after their durable lesson is recorded.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Recreating deleted decisions or plans from README summaries.
|
||||
- Treating imported legacy lessons as if they came from framework-native execution rather than backfill.
|
||||
- Leaving completed migration control artifacts in place after the durable pattern is already preserved.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The migration pattern is now reusable for other domains: retained agendas become new discussions, retained learn becomes legacy lessons, and completed migration control artifacts are disposable after housekeeping.
|
||||
- Legacy source attribution for imported content remains in the imported lessons themselves; this lesson captures the migration pattern rather than one domain-specific document.
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
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`.
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
---
|
||||
id: LSN-0010
|
||||
ticket: packer-docs-import
|
||||
title: Asset identity and runtime contract legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- asset-identity
|
||||
- runtime-contract
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md`.
|
||||
|
||||
This lesson preserves the distinction between stable artifact identity and logical naming.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### `asset_id` and `asset_name` are intentionally different
|
||||
|
||||
**What:** `asset_id` is the stable artifact identity used for runtime-facing stability and preload integrity, while `asset_name` remains a logical, human-facing, code-facing reference.
|
||||
**Why:** Using only `asset_name` makes rename behave like identity breakage, while using only `asset_id` everywhere today makes source-level ergonomics worse. The architecture intentionally keeps both.
|
||||
**Trade-offs:** Carrying both values increases conceptual surface area, but it avoids forcing authoring ergonomics and stable runtime identity into one compromised field.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Use `asset_id` when the question is stable artifact identity.
|
||||
- Use `asset_name` when the question is authoring/reference ergonomics.
|
||||
- Keep both values visible in runtime-facing asset tables.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating rename as identity change.
|
||||
- Treating name-only references as stable preload/bootstrap identity.
|
||||
- Forcing code-facing APIs into raw integer identity too early.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Stable identity and logical naming solve different problems.
|
||||
- Runtime artifact correctness should prefer `asset_id`; human-facing and source-facing flows may still use `asset_name`.
|
||||
- Legacy source attribution: `docs/packer/learn/mental-model-asset-identity-and-runtime-contract.md`.
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
---
|
||||
id: LSN-0011
|
||||
ticket: packer-docs-import
|
||||
title: Foundations workspace runtime and build legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- foundations
|
||||
- deterministic-build
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/packer/learn/foundations-workspace-runtime-and-build.md`.
|
||||
|
||||
This lesson preserves the stable foundation for workspace control, runtime snapshots, writes, and deterministic build output.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### The stable foundation is filesystem-first authoring plus coherent snapshot-backed runtime and deterministic build
|
||||
|
||||
**What:** The packer keeps the workspace open and filesystem-first, anchors managed identity in registry and asset declarations, serves reads through coherent runtime snapshots, coordinates writes through packer-owned lanes, and emits deterministic build outputs from validated state.
|
||||
**Why:** The original implementation wave spread this knowledge across many PR slices, which stopped being a good onboarding surface. The stable model needed one didactic consolidation.
|
||||
**Trade-offs:** This architecture demands stronger ownership of snapshots, write coordination, and deterministic ordering, but it prevents UI heuristics, traversal order, or cache state from silently becoming semantic authority.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Keep `asset_id` stable and separate from `asset_name`.
|
||||
- Treat `asset.json` as authoring intent rather than registry bookkeeping.
|
||||
- Read from coherent runtime snapshots.
|
||||
- Serialize commit-bearing writes through one project-scoped semantic lane.
|
||||
- Order build outputs deterministically by managed identity.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating `asset_name` as stable runtime identity.
|
||||
- Moving registry-owned fields into `asset.json`.
|
||||
- Depending on traversal order or UI order for build layout.
|
||||
- Treating cache state as semantic authority.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The packer foundation is as much about ownership and determinism as it is about file formats.
|
||||
- Filesystem durability, snapshot coherence, and deterministic emission must stay aligned.
|
||||
- Legacy source attribution: `docs/packer/learn/foundations-workspace-runtime-and-build.md`.
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
---
|
||||
id: LSN-0012
|
||||
ticket: packer-docs-import
|
||||
title: Runtime ownership and Studio boundary legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- runtime-boundary
|
||||
- studio-boundary
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/packer/learn/runtime-ownership-and-studio-boundary.md`.
|
||||
|
||||
This lesson preserves the ownership boundary between packer operational semantics and Studio presentation.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Packer owns operational asset semantics; Studio consumes translated responses and events
|
||||
|
||||
**What:** The stable boundary is filesystem-first authoring, project-scoped runtime snapshots for coherent reads, one serialized semantic write lane per project, authoritative packer events with causality, and Studio adapters that translate but do not invent semantics.
|
||||
**Why:** Without this boundary, the system drifts into split-brain behavior where Studio and packer both try to own summaries, mutation meaning, or reconcile logic.
|
||||
**Trade-offs:** Strong semantic ownership in packer makes Studio adapters less flexible, but it keeps lifecycle, concurrency, and event meaning testable and consistent.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Keep divergence explicit packer state rather than silent repair.
|
||||
- Allow coherent `read/read`, serialize `write/write`, and avoid torn `read/write` views.
|
||||
- Preserve operation causality with stable ids and monotonic sequence.
|
||||
- Let Studio remap data for presentation without recomputing semantics.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Rebuilding packer summaries from Studio-side heuristics.
|
||||
- Treating adapters as a second semantic authority.
|
||||
- Hiding divergence by silent refresh.
|
||||
- Allowing same-project writes to race.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Studio should present packer semantics, not recreate them.
|
||||
- Event causality and write-lane ownership are part of the domain contract.
|
||||
- Legacy source attribution: `docs/packer/learn/runtime-ownership-and-studio-boundary.md`.
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
---
|
||||
id: LSN-0013
|
||||
ticket: packer-docs-import
|
||||
title: Metadata convergence and runtime sink legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- metadata
|
||||
- runtime-sink
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md`.
|
||||
|
||||
This lesson preserves the rule that runtime-consumable metadata converges into one effective sink.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Runtime-consumable metadata converges to `AssetEntry.metadata`
|
||||
|
||||
**What:** Authoring contracts may segment metadata by concern, but all runtime-consumable metadata must normalize deterministically into `AssetEntry.metadata`. Payload slicing fields such as `AssetEntry.offset` and `AssetEntry.size` keep their own semantics and do not replace internal indexing values.
|
||||
**Why:** Without an explicit convergence rule, runtime readers, normalization behavior, and metadata collision handling all become accidental and non-deterministic.
|
||||
**Trade-offs:** Deterministic convergence requires explicit normalization rules and collision handling, but it gives runtime consumers one clear reading surface.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Segment metadata in source declarations when useful for authoring ergonomics.
|
||||
- Normalize all runtime-consumable metadata into one root map in emitted asset entries.
|
||||
- Fail or use explicit rules on collisions rather than silently overwriting.
|
||||
- Keep payload slicing and internal indexing semantics distinct.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating segmented declaration metadata as multiple runtime sinks.
|
||||
- Allowing silent key overwrite.
|
||||
- Mixing asset-table slicing semantics with internal indexing offsets.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Runtime consumers should read runtime metadata from `AssetEntry.metadata`.
|
||||
- Convergence behavior must live in specs and tests, not only in code comments.
|
||||
- Legacy source attribution: `docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md`.
|
||||
+47
@@ -0,0 +1,47 @@
|
||||
---
|
||||
id: LSN-0014
|
||||
ticket: packer-docs-import
|
||||
title: Pack wizard summary validation and pack execution legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- pack-wizard
|
||||
- validation
|
||||
- execution
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md`.
|
||||
|
||||
This lesson preserves the packer-owned semantics behind the Studio-side pack wizard.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Summary, validation, and pack execution are distinct packer-owned phases
|
||||
|
||||
**What:** `summary` is a fast snapshot-backed preflight view, `validation` is a blocking-diagnostics gate over the same active pack set, and `packWorkspace(...)` is the only artifact-emitting operation, rerunning the gate on a fresh frozen snapshot and promoting staged outputs only after coherent success.
|
||||
**Why:** Studio-side shelling only works if packer provides one coherent operational story instead of a mix of stale UI assumptions and live filesystem rereads.
|
||||
**Trade-offs:** This model is stricter and less forgiving than trusting previous UI state, but it prevents stale or torn assumptions from leaking into final build output.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Define the active pack set as `registered + included in build`.
|
||||
- Keep summary fast and snapshot-backed.
|
||||
- Let only blocking diagnostics fail first-wave validation.
|
||||
- Re-run the gate on a fresh execution snapshot before emission.
|
||||
- Stage outputs before promoting them to final `build/`.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating summary as emitted-artifact preview.
|
||||
- Validating a broader set than the active pack set.
|
||||
- Letting warnings fail the first-wave gate.
|
||||
- Reading live filesystem bytes after frozen execution starts.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Green validation from a few seconds earlier is not enough; pack execution must revalidate on a fresh frozen snapshot.
|
||||
- Packer-owned result semantics should be enough for Studio to render packing and result phases.
|
||||
- Legacy source attribution: `docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md`.
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
---
|
||||
id: LSN-0015
|
||||
ticket: packer-docs-import
|
||||
title: Tile bank packing contract legacy lesson
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- tile-bank
|
||||
- packing-contract
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/packer/learn/tile-bank-packing-contract.md`.
|
||||
|
||||
This lesson preserves the first-wave producer contract for tile-bank assets.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Tile bank packing emits one canonical payload per asset with explicit normalization and early structural validation
|
||||
|
||||
**What:** The first-wave contract emits one canonical `TILES/indexed_v1` payload per asset, normalizes artifacts by explicit `artifacts[*].index`, packs one fixed `256 x 256` row-major sheet with packed `u4` pixels and `RGB565` palette blocks, treats palette identity as semantic rather than positional, and surfaces structural blockers early in walker/materialization.
|
||||
**Why:** The repository needed one explicit producer contract for tile banks rather than a mix of implicit artifact ordering, late byte-emission surprises, and unstable palette identity.
|
||||
**Trade-offs:** This contract is more explicit and restrictive than ad hoc per-artifact packing, but it yields stable reviewability, predictable runtime metadata, and earlier validation.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Treat `1 artifact = 1 tile`.
|
||||
- Normalize artifact identity by ascending declared `index`.
|
||||
- Emit one canonical bank raster rather than concatenated artifact-local binaries.
|
||||
- Keep palette identity explicit with `{ index, palette }`.
|
||||
- Produce structural diagnostics before late pack-only phases.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating artifact declaration order as semantic tile identity.
|
||||
- Embedding per-tile palette choice in packed payload.
|
||||
- Flattening all metadata into one ambiguous map.
|
||||
- Discovering tile-bank blockers only during final byte emission.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The tile-bank producer contract depends on canonical normalization and early structural validation.
|
||||
- Palette identity should be semantic and explicit, not positional by list order.
|
||||
- Legacy source attribution: `docs/packer/learn/tile-bank-packing-contract.md`.
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
id: LSN-0017
|
||||
ticket: packer-docs-import
|
||||
title: Packer docs import pattern
|
||||
created: 2026-03-26
|
||||
tags:
|
||||
- packer
|
||||
- migration
|
||||
- discussion-framework
|
||||
- import-pattern
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
This lesson summarizes the completed migration of `docs/packer` into `discussion/`.
|
||||
|
||||
The original migration control artifacts were:
|
||||
|
||||
- `AGD-0003`
|
||||
- `DEC-0002`
|
||||
- `PLN-0002`
|
||||
|
||||
Those workflow files are being deleted during housekeeping. The index remains the permanent historical record.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Packer domain import follows the same retained-set migration pattern as Studio
|
||||
|
||||
**What:** The `docs/packer` migration imported only retained artifacts, promoted retained open agendas into new discussions, preserved the empty retained sets for decisions and plans, rewrote retained `learn` into legacy lessons, and kept `specs` outside `discussion/`.
|
||||
**Why:** The packer domain already had two live agendas and a didactic learn corpus, but no retained decisions or plans. The migration needed to preserve that real operational state instead of fabricating symmetry.
|
||||
**Trade-offs:** The pattern keeps workflow truth honest, but it requires explicit editorial rewriting and separate migration bookkeeping before the resulting discussions can continue normally.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Treat README-declared empty retained sets as authoritative.
|
||||
- Create one new discussion per retained agenda.
|
||||
- Backfill retained learn documents as legacy lessons in the migration discussion directory.
|
||||
- Keep normative specs external to the workflow control plane.
|
||||
- Delete completed migration control artifacts after recording the durable pattern lesson.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Manufacturing missing decisions or plans to make the imported tree look symmetric.
|
||||
- Forgetting to separate imported open agendas into their own discussions.
|
||||
- Keeping completed migration scaffolding around after the lesson already captures the reusable pattern.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Domain migration is a repeatable workflow: preserve retained truth, normalize into framework templates, split open agendas into real discussions, and delete completed migration scaffolding after housekeeping.
|
||||
- This lesson captures the migration pattern; the imported packer legacy lessons capture the domain knowledge itself.
|
||||
+53
@@ -0,0 +1,53 @@
|
||||
---
|
||||
id: LSN-0018
|
||||
ticket: pbs-learn-to-discussion-lessons-migration
|
||||
title: PBS AST and Parser Contract Legacy Import
|
||||
created: 2026-03-27
|
||||
tags: [compiler, pbs, legacy-import, ast, parser, diagnostics]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/compiler/pbs/learn/01. AST and Parser Contract.md`.
|
||||
|
||||
This lesson preserves the durable parser-facing contract that remained after the PBS workflow prune.
|
||||
It records what later phases are allowed to assume about AST structure without freezing one parser implementation strategy.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Obligations-first AST contract
|
||||
|
||||
**What:** PBS standardizes observable AST obligations rather than one mandatory in-memory representation.
|
||||
|
||||
**Why:** Downstream phases need deterministic structure and attribution, but the repository does not want to lock parser architecture or implementation language.
|
||||
|
||||
**Trade-offs:** The contract is flexible for implementation, but it requires strong conformance discipline around spans, node families, and rejection behavior.
|
||||
|
||||
### Recovery must preserve structural honesty
|
||||
|
||||
**What:** Parser recovery is allowed only when the recovered AST remains structurally coherent and attribution-safe.
|
||||
|
||||
**Why:** Recovery exists to keep diagnostics useful, not to hide invalid syntax behind permissive fake trees.
|
||||
|
||||
**Trade-offs:** This makes parser implementations slightly stricter, but it prevents later phases from operating on misleading AST shapes.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Treat AST as a structural boundary, not a semantic one.
|
||||
- Preserve declaration identity instead of collapsing overloads or rewriting source-observable parse outcomes.
|
||||
- Make precedence and associativity visible in AST shape, because they are part of the user-observable contract.
|
||||
- Require stable source attribution on every node that diagnostics or lowering may consume.
|
||||
- Keep diagnostic identity locale-agnostic; wording is not the conformance key.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Rewriting AST after parse in a way that changes observable parse meaning.
|
||||
- Allowing recovery to downgrade a required rejection into an accepted semantic shape.
|
||||
- Emitting nodes without enough attribution for diagnostics or lowering.
|
||||
- Treating localized message strings as conformance identity.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- PBS AST is standardized by obligations, not by one exact object model.
|
||||
- Parser recovery is acceptable only when it stays structurally honest.
|
||||
- Attribution and deterministic rejection are first-class parser contracts, not secondary details.
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
---
|
||||
id: LSN-0019
|
||||
ticket: pbs-learn-to-discussion-lessons-migration
|
||||
title: PBS Name Resolution and Linking Legacy Import
|
||||
created: 2026-03-27
|
||||
tags: [compiler, pbs, legacy-import, linking, name-resolution, imports]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/compiler/pbs/learn/02. Name Resolution and Linking.md`.
|
||||
|
||||
This lesson preserves the durable namespace and phase-boundary model for PBS frontend resolution after the domain workflow artifacts were pruned.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Module scope is assembled before visibility filtering
|
||||
|
||||
**What:** PBS collects declarations across all `.pbs` files in a module before `mod.barrel` visibility is applied.
|
||||
|
||||
**Why:** `mod.barrel` is a visibility filter, not a declaration factory.
|
||||
|
||||
**Trade-offs:** Module assembly must be explicit and deterministic, but the resulting linking model is much cleaner.
|
||||
|
||||
### Linking owns visible-space conflicts
|
||||
|
||||
**What:** Different-origin imported collisions, local-versus-import clashes, and barrel-driven visibility conflicts are rejected in linking before callsite analysis.
|
||||
|
||||
**Why:** Static semantics should operate only after the visible declaration space is already unambiguous.
|
||||
|
||||
**Trade-offs:** Linking becomes stricter, but overload resolution and typing stop carrying unrelated ambiguity debt.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Build module scope before import visibility decisions.
|
||||
- Resolve callable imports as exported callable sets, not isolated overload fragments.
|
||||
- Reject same-name different-origin conflicts before overload resolution.
|
||||
- Keep builtin simple types separate from imported builtin shells.
|
||||
- Treat aliasing as local spelling only; canonical identity must remain stable.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating `mod.barrel` as if it creates declarations.
|
||||
- Deferring imported-origin conflicts until callsite resolution.
|
||||
- Letting local and imported same-name declarations silently coexist.
|
||||
- Promoting imported builtin shells to the same status as always-available builtin simple types.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Linking decides what is visible; static semantics decides what a visible thing means.
|
||||
- `mod.barrel` filters visibility but does not define declaration existence.
|
||||
- Canonical identity must outrank textual spelling during import and linking work.
|
||||
+57
@@ -0,0 +1,57 @@
|
||||
---
|
||||
id: LSN-0020
|
||||
ticket: pbs-learn-to-discussion-lessons-migration
|
||||
title: PBS Runtime Values, Identity, and Memory Boundaries Legacy Import
|
||||
created: 2026-03-27
|
||||
tags: [compiler, pbs, legacy-import, runtime, values, identity, memory]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.md`.
|
||||
|
||||
This lesson preserves the runtime-facing mental model that keeps PBS lowering, diagnostics, and future optimization work aligned on aliasing, retention, and ownership.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Value categories are explicit
|
||||
|
||||
**What:** PBS distinguishes copied payload values, identity-bearing values, and carrier-only values.
|
||||
|
||||
**Why:** Later lowering and diagnostics need a stable answer to whether a construct preserves aliasing, creates retention, or just transports an existing payload.
|
||||
|
||||
**Trade-offs:** The model is intentionally qualitative rather than layout-specific, which keeps it stable but less byte-accounting-friendly.
|
||||
|
||||
### Host boundary semantics remain explicit
|
||||
|
||||
**What:** Host interaction is stack-only across the boundary, but host-backed resources still count as identity-bearing on the PBS side.
|
||||
|
||||
**Why:** PBS needs a clean boundary without pretending that host ownership disappears once a value crosses into language semantics.
|
||||
|
||||
**Trade-offs:** This is semantically clean, but it requires implementers to avoid naive “stack-only means no ownership complexity” shortcuts.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Treat scalars as copied payload without user-visible identity.
|
||||
- Treat structs, services, and host-backed resources as identity-bearing.
|
||||
- Treat tuples, `optional`, and `result` as carriers that do not create identity of their own.
|
||||
- Interpret cost visibility semantically:
|
||||
- allocation-bearing,
|
||||
- retention-bearing,
|
||||
- copy versus aliasing,
|
||||
- host-boundary crossing,
|
||||
- trap possibility.
|
||||
- Keep future lifetime-control and concurrency surfaces out of `core-v1` unless explicitly claimed.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Assuming carrier types create fresh identity.
|
||||
- Confusing qualitative runtime guarantees with exact allocator or collector promises.
|
||||
- Assuming stack-only host crossing eliminates host ownership concerns.
|
||||
- Silently treating future-profile surfaces as current supported behavior.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- PBS runtime contracts are qualitative on purpose.
|
||||
- Identity, aliasing, and retention are the stable facts that matter most for maintenance.
|
||||
- Host authority and PBS semantic identity can coexist without contradiction.
|
||||
+51
@@ -0,0 +1,51 @@
|
||||
---
|
||||
id: LSN-0021
|
||||
ticket: pbs-learn-to-discussion-lessons-migration
|
||||
title: PBS Diagnostics and Conformance Governance Legacy Import
|
||||
created: 2026-03-27
|
||||
tags: [compiler, pbs, legacy-import, diagnostics, conformance, governance]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/compiler/pbs/learn/04. Diagnostics and Conformance Governance.md`.
|
||||
|
||||
This lesson preserves the durable governance rules that survived the migration of broad policy ownership into general compiler specs.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Diagnostics are stable by identity, not prose
|
||||
|
||||
**What:** Diagnostic correctness is keyed by stable identity fields rather than by localized or rendered wording.
|
||||
|
||||
**Why:** Conformance and regression evidence must survive wording changes and localization.
|
||||
|
||||
**Trade-offs:** Tooling must carry identity fields seriously, but the resulting diagnostic contract is auditable and stable.
|
||||
|
||||
### Published claims require executable evidence
|
||||
|
||||
**What:** Conformance, compatibility, and support claims must be backed by maintained tests or artifact checks appropriate to the claim level.
|
||||
|
||||
**Why:** Published support without executable proof creates documentation debt and ambiguous promises.
|
||||
|
||||
**Trade-offs:** Governance becomes stricter, but support language stops drifting away from the real implementation.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Prefer general compiler specs as the live owner for cross-language governance.
|
||||
- Keep PBS-local guidance only for PBS-specific deltas and lessons.
|
||||
- Align claim scope, tests, and compatibility language together.
|
||||
- Be explicit when a surface is rescope-only rather than partially supported.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Leaving superseded local policy docs around as if they still owned the contract.
|
||||
- Publishing support claims without maintained evidence.
|
||||
- Allowing compatibility matrices and tests to drift apart.
|
||||
- Leaving rescope decisions implicit, especially for deferred execution surfaces.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Diagnostics and conformance must stay executable and auditable.
|
||||
- Once general specs take ownership, PBS-local records should become lesson material rather than live policy.
|
||||
- Honest rescoping is better than ambiguous “deferred” support language.
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
---
|
||||
id: LSN-0022
|
||||
ticket: pbs-learn-to-discussion-lessons-migration
|
||||
title: PBS Globals, Lifecycle, and Published Entrypoint Legacy Import
|
||||
created: 2026-03-27
|
||||
tags: [compiler, pbs, legacy-import, globals, lifecycle, entrypoint, lowering]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Legacy import from `docs/compiler/pbs/learn/05. Globals, Lifecycle, and Published Entrypoint.md`.
|
||||
|
||||
This lesson preserves the final topic-19 executable model after the workflow history was pruned from the PBS domain.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Logical frame root and physical entrypoint are separate
|
||||
|
||||
**What:** The user `[Frame]` callable is the logical frame root, while the compiler-published wrapper is the physical executable entrypoint.
|
||||
|
||||
**Why:** The language surface should stay clean and semantically owned by user code, while the compiler owns the executable boot protocol.
|
||||
|
||||
**Trade-offs:** The model introduces synthetic artifacts, but it makes lifecycle orchestration explicit and deterministic.
|
||||
|
||||
### Boot is one-shot and compiler-owned
|
||||
|
||||
**What:** PBS boot orchestration is enforced through compiler-generated lifecycle artifacts plus a hidden boot guard.
|
||||
|
||||
**Why:** One-shot bootstrap semantics cannot depend on naming convention or informal runtime discipline.
|
||||
|
||||
**Trade-offs:** Lowering must carry more structure and metadata, but backend and runtime contracts become much less ambiguous.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Model globals as explicit source-level declarations with stable module ownership.
|
||||
- Model lifecycle through `[Init]`, `[Frame]`, and compiler-owned synthetic lowering artifacts.
|
||||
- Publish the wrapper at physical entrypoint index `0`.
|
||||
- Keep `FRAME_RET` in the wrapper path, not at the end of userland `frame()`.
|
||||
- Keep hidden lifecycle state structurally distinguishable from ordinary user globals and callables.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating `frame()` itself as the physical entrypoint.
|
||||
- Reintroducing manifest-driven entrypoint authority.
|
||||
- Recognizing hidden lifecycle artifacts only by naming convention.
|
||||
- Proving only artifact presence without proving one-shot bootstrap semantics.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Userland owns frame semantics; the compiler owns executable boot protocol.
|
||||
- Hidden lifecycle artifacts must be first-class structure, not naming folklore.
|
||||
- Topic 19 is the closure that made PBS executable publication deterministic end-to-end.
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
id: AGD-0002
|
||||
ticket: palette-management-in-studio
|
||||
title: Palette Management in Studio
|
||||
status: open
|
||||
created: 2026-03-26
|
||||
resolved:
|
||||
decision:
|
||||
tags:
|
||||
- studio
|
||||
- legacy-import
|
||||
- palette-management
|
||||
- tile-bank
|
||||
- packer-boundary
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Studio already has a retained agenda for palette management in the `tile bank` form session, but that agenda exists only under `docs/studio/agendas/` and therefore sits outside the discussion-framework lifecycle.
|
||||
|
||||
Without importing it into `discussion/`, the canonical discussion surface would lose the still-open Studio question about:
|
||||
|
||||
- how candidate palettes are presented;
|
||||
- how `1..64` palette capacity is enforced and explained;
|
||||
- how preview and selection behave inside the asset workflow;
|
||||
- how Studio UX stays separate from packer-owned extraction, validation, identity, and persistence.
|
||||
|
||||
## Context
|
||||
|
||||
Legacy source: `docs/studio/agendas/Palette Management in Studio Agenda.md`
|
||||
|
||||
Domain owner: `docs/studio`
|
||||
Cross-domain impact: `docs/packer`
|
||||
|
||||
The retained agenda is intentionally scoped to `tile bank`.
|
||||
|
||||
The imported context keeps the same baseline:
|
||||
|
||||
- every `*.png` input of a tile bank is one tile;
|
||||
- each tile yields one extracted palette during cache construction;
|
||||
- developers may also work with favorite palettes and asset palettes;
|
||||
- each bank may integrate at most `64` palettes;
|
||||
- each palette contains `16` colors with a default color-key baseline;
|
||||
- Studio owns curation UX, while packer remains authoritative for extraction, identity, validation, and persistence.
|
||||
|
||||
The current UI shape already converged on:
|
||||
|
||||
- a left-side transfer list for candidate and selected palettes;
|
||||
- custom palette rendering with swatches and source indicators;
|
||||
- a right-side preview panel with tile/file selector, tile preview, and applied palette strip.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] How should Studio detect and present duplicate or near-equivalent palettes across tile-derived, favorite, and asset-level sources?
|
||||
- [ ] Are favorites project-scoped references to existing palettes, or can they diverge into editable copies before bank admission?
|
||||
- [ ] What is the canonical user-facing identity of a candidate palette in Studio: source bucket plus logical name, file path, extraction origin tile, stable id, or a combination?
|
||||
- [ ] Should extracted tile palettes always enter the candidate set automatically, or can the developer suppress some of them before curation?
|
||||
- [ ] Should clicking a palette on the `selected` side be the only interaction needed to change the previewed palette in the first wave?
|
||||
- [ ] Which palette operations are read-only in the first wave, and which require staged preview/apply treatment?
|
||||
- [ ] Which parts of this interaction model should remain explicitly `tile bank`-specific, and which parts are reusable Studio form-session primitives?
|
||||
- [ ] Does the first release need only an asset-scoped `tile bank` section, or also a project-level palette browser for discovery and favorites management?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Automatic Integration
|
||||
- **Approach:** Treat extracted tile palettes as implicit inputs and integrate them automatically without explicit user curation.
|
||||
- **Pro:** Lowest immediate UX cost.
|
||||
- **Con:** Hides palette-budget reasoning, weakens deliberate composition, and makes source distinctions harder to understand.
|
||||
- **Maintainability:** Weak. It pushes important bank rules into implicit behavior.
|
||||
|
||||
### Option B - Asset-Scoped Curated Selection
|
||||
- **Approach:** Treat bank palettes as an asset-scoped curated selection built from tile-derived palettes, favorites, and asset palettes, with Studio owning the curation UX and packer owning persistence.
|
||||
- **Pro:** Matches the concrete `tile bank` workflow and keeps authority boundaries clear.
|
||||
- **Con:** Requires explicit UX for capacity, identity, deduplication, and preview semantics.
|
||||
- **Maintainability:** Strong. It makes responsibilities explicit and keeps family-specific rules close to the workflow that needs them.
|
||||
|
||||
### Option C - Studio-Owned Palette Library
|
||||
- **Approach:** Treat palettes as a broader Studio-owned library/workspace with direct local editing and persistence behavior.
|
||||
- **Pro:** Potentially flexible for future palette-heavy features.
|
||||
- **Con:** Duplicates packer ownership and risks creating a second authority for bank composition.
|
||||
- **Maintainability:** Weak. It expands Studio responsibility before the persistence contract is closed.
|
||||
|
||||
## Discussion
|
||||
|
||||
The imported agenda keeps the original recommendation intact: palette management should be first-class for `tile bank`, but Studio must not become the persistence authority.
|
||||
|
||||
That means the key open problem is not whether palettes exist. It is how Studio explains and curates them safely:
|
||||
|
||||
- candidate aggregation from multiple sources;
|
||||
- clear source and identity display;
|
||||
- explicit `1..64` capacity feedback;
|
||||
- a preview model that stays tied to the selected bank palettes;
|
||||
- a boundary between `tile bank`-specific UX and reusable Studio primitives.
|
||||
|
||||
The retained source already converged on a pragmatic first wave:
|
||||
|
||||
- transfer-list selection on the left;
|
||||
- palette-focused preview on the right;
|
||||
- first selected palette as default preview;
|
||||
- clicking on a selected palette changes the previewed palette;
|
||||
- removing the current preview palette falls back to the first remaining selected palette.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recommended direction: adopt **Option B**.
|
||||
|
||||
The imported agenda preserves the retained Studio direction:
|
||||
|
||||
1. palette management belongs to the `tile bank` asset workflow;
|
||||
2. Studio aggregates candidate palettes from tile-derived extraction, favorites, and asset palettes;
|
||||
3. the first wave uses a custom-rendered transfer list with an explicit `1..64` selected range;
|
||||
4. the right-side preview panel stays tied to the current selected palette set;
|
||||
5. packer remains authoritative for extraction, identity, validation, and persistence;
|
||||
6. broader standalone palette-authoring workflows remain deferred.
|
||||
|
||||
Next step suggestion: convert this imported agenda into a decision that closes the ownership boundary, candidate-source model, first-wave transfer-list UX, preview behavior, and reusable-vs-family-specific primitive boundary.
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
id: AGD-0004
|
||||
ticket: tilemap-and-metatile-runtime-binary-layout
|
||||
title: Tilemap and Metatile Runtime Binary Layout
|
||||
status: open
|
||||
created: 2026-03-26
|
||||
resolved:
|
||||
decision:
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- tilemap
|
||||
- metatile
|
||||
- runtime-layout
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
The repository has conceptual alignment around map responsibility split and active-window residency, but still lacks a closed runtime binary contract for handheld maps.
|
||||
|
||||
Without a canonical decision:
|
||||
|
||||
- packer cannot close the output specification for map artifacts;
|
||||
- runtime lacks one stable reading baseline;
|
||||
- Studio cannot align authoring and preview schemas with one binary target.
|
||||
|
||||
## Context
|
||||
|
||||
Legacy source: `docs/packer/agendas/Tilemap and Metatile Runtime Binary Layout Agenda.md`
|
||||
|
||||
Domain owner: `docs/packer`
|
||||
Cross-domain impact:
|
||||
|
||||
- `docs/vm-arch`
|
||||
- `docs/studio`
|
||||
- `docs/compiler/pbs`
|
||||
|
||||
Current discussion premises retained from source:
|
||||
|
||||
- visual and collision concerns should remain separated;
|
||||
- map cells should not duplicate large metadata per tile;
|
||||
- only a `3x3` active window of maps should remain resident in memory;
|
||||
- a `64 KiB` target budget per map bank has been discussed;
|
||||
- `map bank` and `tileset bank` do not need identical size rules.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Is `collisionId` with `5` bits (`32` classes) sufficient for expected projects?
|
||||
- [ ] Should `flag0` be reserved for fast trigger semantics or contextual visual variation?
|
||||
- [ ] Which optional chunks belong in `V1`, and which should wait for a later version?
|
||||
- [ ] Must `map bank` stay strictly at `64 KiB`, or should capacity be variable with explicit metadata?
|
||||
- [ ] What compression policy should the packer adopt by default for the stream?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - `u8` cells with auxiliary tables
|
||||
- **Approach:** Store only one `metatileId` per cell and derive collision/flags from side tables.
|
||||
- **Pro:** Smallest RAM and I/O footprint.
|
||||
- **Con:** Pushes too much semantic meaning into external lookup tables.
|
||||
- **Maintainability:** Medium.
|
||||
|
||||
### Option B - `u16` bit-packed cells
|
||||
- **Approach:** Use `16` bits per cell, with a compact split such as `visualId`, `collisionId`, and `flag0`.
|
||||
- **Pro:** Balances compactness, deterministic decoding, and enough expressivity for many handheld cases.
|
||||
- **Con:** Leaves less room for inline per-cell growth than `u32`.
|
||||
- **Maintainability:** Strong.
|
||||
|
||||
### Option C - `u32` cells
|
||||
- **Approach:** Use larger cells to keep more event/flag space inline.
|
||||
- **Pro:** Highest flexibility for per-cell triggers and future expansion.
|
||||
- **Con:** Doubles memory cost versus `u16` without current evidence that it is needed.
|
||||
- **Maintainability:** Weak for the current budget target.
|
||||
|
||||
## Discussion
|
||||
|
||||
The retained source already converged toward `u16` as the best baseline.
|
||||
|
||||
The suggested runtime shape is:
|
||||
|
||||
- fixed map header;
|
||||
- contiguous cell stream;
|
||||
- optional future-proof chunks.
|
||||
|
||||
The proposed `U16_PACKED_V1` split keeps visual and collision references compact while preserving predictable memory usage and straightforward streaming behavior for a handheld target.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recommended direction: adopt **Option B** as the baseline.
|
||||
|
||||
Imported retained recommendation:
|
||||
|
||||
1. authorship stays JSON-oriented around compact ids;
|
||||
2. build output packs deterministically into `U16_PACKED_V1`;
|
||||
3. runtime active-window budget remains explicit;
|
||||
4. any move to `u32` should happen only through a later versioned encoding with evidence of need.
|
||||
|
||||
Next step suggestion: convert this agenda into a decision that closes `U16_PACKED_V1`, propagation to `docs/vm-arch`, Studio editing schema alignment, and implementation planning for roundtrip tests.
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
id: AGD-0005
|
||||
ticket: variable-tile-bank-palette-serialization
|
||||
title: Variable Tile Bank Palette Serialization
|
||||
status: open
|
||||
created: 2026-03-26
|
||||
resolved:
|
||||
decision:
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- tile-bank
|
||||
- palette-serialization
|
||||
- versioning
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
The current tile-bank contract serializes a fixed block of `64` palettes in v1 even when an asset authors far fewer palettes.
|
||||
|
||||
That keeps decoding simple, but it wastes cartridge space and leaves the system with a deliberate mismatch between authored and serialized palette counts.
|
||||
|
||||
## Context
|
||||
|
||||
Legacy source: `docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md`
|
||||
|
||||
Domain owner: `docs/packer`
|
||||
Cross-domain dependency:
|
||||
|
||||
- runtime
|
||||
|
||||
Current aligned v1 contract:
|
||||
|
||||
- pixels are serialized as packed `u4`;
|
||||
- palettes are serialized as `RGB565 u16`;
|
||||
- `palette_count = 64`;
|
||||
- payload size includes a fixed `64 * 16 * 2` palette block.
|
||||
|
||||
The packer now exposes:
|
||||
|
||||
- `metadata.palette_count = 64`
|
||||
- `metadata.palette_authored = <actual authored count>`
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Should variable palette serialization arrive as a new payload version or as an incompatible change to the current one?
|
||||
- [ ] If `palette_count` becomes variable, should runtime still materialize a 64-slot resident bank, or truly shrink in-memory representation too?
|
||||
- [ ] Should sparse authored palette indices remain sparse in serialization, or be canonicalized into a dense runtime block?
|
||||
- [ ] Which domain owns compatibility for existing cartridges: `packer`, `runtime`, or `shipper`?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Keep fixed 64-palette serialization
|
||||
- **Approach:** Preserve the current fixed v1 payload with zero-filled unused palette slots.
|
||||
- **Pro:** No runtime change and current specs/tests remain stable.
|
||||
- **Con:** Every tile bank keeps paying the full palette cost.
|
||||
- **Maintainability:** Medium.
|
||||
|
||||
### Option B - Move to variable palette serialization now
|
||||
- **Approach:** Serialize only authored palettes and shrink payload size immediately.
|
||||
- **Pro:** Better cartridge efficiency and tighter semantics for `palette_count`.
|
||||
- **Con:** Reopens a just-stabilized cross-domain runtime contract and forces compatibility decisions now.
|
||||
- **Maintainability:** Medium if done carefully, risky if done incidentally.
|
||||
|
||||
### Option C - Keep v1 fixed and design variable serialization for v2
|
||||
- **Approach:** Preserve v1 stability now and open a later versioned follow-up for variable palette serialization.
|
||||
- **Pro:** Keeps current work stable while preserving a clean path for future optimization.
|
||||
- **Con:** Known waste remains in v1.
|
||||
- **Maintainability:** Strong.
|
||||
|
||||
## Discussion
|
||||
|
||||
The retained agenda recommendation is already clear: the waste is real, but it is not a correctness bug, and reopening the runtime-facing contract immediately would mix optimization work into a freshly stabilized path.
|
||||
|
||||
That makes versioned follow-up a cleaner vehicle than incidental mutation of the current contract.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recommended direction: adopt **Option C**.
|
||||
|
||||
Imported retained recommendation:
|
||||
|
||||
1. keep the current fixed 64-palette contract for v1;
|
||||
2. if variable serialization is desired, design it explicitly as a versioned follow-up;
|
||||
3. treat compatibility, runtime representation, and sparse-vs-dense palette identity as explicit next-wave questions rather than silent payload tweaks.
|
||||
|
||||
Next step suggestion: if the team wants to remove the fixed padding, open the corresponding runtime-side discussion and close the versioning/compatibility story before planning implementation.
|
||||
+94
@@ -0,0 +1,94 @@
|
||||
---
|
||||
id: AGD-0006
|
||||
ticket: pbs-game-facing-asset-refs-and-call-result-discard
|
||||
title: PBS Game-Facing Asset References and Ignored Call Result Lowering
|
||||
status: open
|
||||
created: 2026-03-27
|
||||
resolved:
|
||||
decision:
|
||||
tags: [compiler, pbs, ergonomics, lowering, runtime, asset-identity, expression-statements]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
PBS ainda tem dois atritos abertos na fronteira entre ergonomia de código de jogo e lowering executável:
|
||||
|
||||
1. referências a assets continuam centradas em `asset_name` no código-fonte, enquanto packer/runtime já convergiram para identidade estável por `asset_id`;
|
||||
2. `expression statements` com retorno materializado ainda precisam de política explícita de descarte, para não vazar regra de stack do backend para o código de usuário.
|
||||
|
||||
Os dois temas pertencem à mesma discussão porque tratam da mesma pergunta arquitetural:
|
||||
|
||||
Como PBS deve preservar uma superfície de autoria natural sem sacrificar determinismo no lowering e no runtime?
|
||||
|
||||
## Context
|
||||
|
||||
Esta agenda consolida dois tópicos legados do domínio PBS:
|
||||
|
||||
- `18.4. Asset References in Game Code - Names vs Compile-Time Lowering`
|
||||
- `18.5. Ignored Call Results in Executable Lowering`
|
||||
|
||||
Os pontos estáveis já conhecidos são:
|
||||
|
||||
- packer/runtime tratam `asset_id` como identidade estável;
|
||||
- `asset_name` ainda é a superfície mais natural para autoria e tooling;
|
||||
- o pipeline executável hoje já exige disciplina explícita de stack;
|
||||
- a família `19` reforçou a direção de compiler-owned lowering e publication protocol, reduzindo espaço para ambiguidades “aceitas pelo frontend, rejeitadas mais tarde”.
|
||||
|
||||
Isso sugere um princípio comum:
|
||||
|
||||
- a linguagem pode continuar amigável na superfície,
|
||||
- mas o compiler precisa assumir explicitamente o trabalho de normalizar essa superfície para um contrato executável estável.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Referências a asset devem permanecer nomeadas na superfície PBS, mesmo se o lowering resolver parte delas para identidade estável?
|
||||
- [ ] O descarte de retorno ignorado deve ser uma regra geral de `expression statement`, ou uma exceção localizada para certos callsites?
|
||||
- [ ] Até onde PBS quer empurrar “surface ergonomics, compiler normalization” como princípio geral para APIs de jogo?
|
||||
- [ ] Quais casos precisam continuar dinâmicos em runtime e portanto não podem ser lowered agressivamente em compile time?
|
||||
- [ ] Devemos publicar warnings opcionais para retorno ignorado ou rename-fragile asset references, ou isso fica fora do escopo inicial?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Keep Surface Simple, Keep Runtime Rules Visible
|
||||
- **Approach:** manter `asset_name` como referência de longo prazo e exigir consumo explícito de retornos quando houver valor materializado.
|
||||
- **Pro:** modelo simples e pouco invasivo.
|
||||
- **Con:** vaza custo operacional e detalhe de lowering para código-fonte; mantém fragilidade de rename e lookup tardio.
|
||||
- **Maintainability:** baixa a média, porque o autor continua negociando diretamente com limites do backend/runtime.
|
||||
|
||||
### Option B - Preserve Surface Ergonomics, Normalize in the Compiler
|
||||
- **Approach:** manter superfície amigável (`asset_name`, `foo();`) e explicitar no compiler as normalizações necessárias, como lowering para identidade estável quando possível e descarte automático de resultados ignorados em `expression statement`.
|
||||
- **Pro:** separa melhor autoria de protocolo executável; fica alinhado com a direção já adotada na família `19`.
|
||||
- **Con:** aumenta responsabilidade do compiler e exige regras claras de quando a normalização pode ou não ocorrer.
|
||||
- **Maintainability:** alta, porque o contrato passa a ficar onde ele deveria estar: no compiler e nas specs de lowering.
|
||||
|
||||
### Option C - Introduce Rich Resource and Effect Surfaces
|
||||
- **Approach:** criar abstrações mais fortes para recursos e resultados descartáveis, com novos tipos/superfícies na linguagem.
|
||||
- **Pro:** potencialmente o modelo mais explícito e expressivo no longo prazo.
|
||||
- **Con:** escopo bem maior; mistura redesign de linguagem com problemas que talvez possam ser resolvidos por lowering.
|
||||
- **Maintainability:** incerta no curto prazo; só compensa se PBS quiser investir em abstrações novas, não apenas fechar lacunas atuais.
|
||||
|
||||
## Discussion
|
||||
|
||||
As duas agendas legadas apontam para a mesma direção recomendada:
|
||||
|
||||
- preservar ergonomia de autoria;
|
||||
- e mover o peso de normalização para o compiler.
|
||||
|
||||
Isso não significa “magia implícita sem limite”.
|
||||
Significa assumir, de forma normativa, que a superfície PBS pode ser mais estável e legível do que o protocolo executável final.
|
||||
|
||||
O ponto central desta discussão é definir o limite dessa política:
|
||||
|
||||
- quando PBS só normaliza lowering,
|
||||
- e quando precisa criar uma abstração nova de linguagem.
|
||||
|
||||
## Resolution
|
||||
|
||||
Direção recomendada por enquanto:
|
||||
|
||||
1. tratar os dois temas como uma única discussão de política de surface-versus-lowering em PBS;
|
||||
2. preferir a direção **Option B** como baseline;
|
||||
3. fechar depois duas decisões derivadas:
|
||||
- política de asset references para código de jogo;
|
||||
- política de descarte de retorno ignorado em `expression statement`;
|
||||
4. evitar introduzir nova abstração de linguagem antes de esgotar a via de normalização no compiler.
|
||||
Reference in New Issue
Block a user