discussion framework migration

This commit is contained in:
2026-03-27 04:38:15 +00:00
parent abdb28aa68
commit e582527937
31 changed files with 17 additions and 17 deletions
@@ -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`.
@@ -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`.
@@ -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`.
@@ -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`.
@@ -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`.
@@ -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`.
@@ -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`.
@@ -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`.
@@ -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`.
@@ -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`.
@@ -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`.
@@ -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`.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.