From 0e5e1669c2537544cb49dc2a219ac963a7a6011f Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 20 Mar 2026 15:48:10 +0000 Subject: [PATCH] clean up --- docs/packer/README.md | 9 +- ...zard Studio Decision Propagation Agenda.md | 295 ------------------ docs/packer/agendas/README.md | 6 +- ...ile Bank Packing Materialization Agenda.md | 258 --------------- ...y, and Studio Adapter Boundary Decision.md | 130 -------- ...Runtime and Reconcile Boundary Decision.md | 175 ----------- ...ergence to AssetEntry.metadata Decision.md | 146 --------- ...izard Pack Execution Semantics Decision.md | 218 ------------- ...mmary and Validation Contracts Decision.md | 174 ----------- docs/packer/decisions/README.md | 13 +- ...e Bank Packing Materialization Decision.md | 211 ------------- docs/packer/learn/README.md | 6 +- ...foundations-workspace-runtime-and-build.md | 91 ++++++ ...l-metadata-convergence-and-runtime-sink.md | 8 +- ...d-summary-validation-and-pack-execution.md | 118 +++++++ .../runtime-ownership-and-studio-boundary.md | 88 ++++++ .../learn/tile-bank-packing-contract.md | 116 +++++++ ...project-bootstrap-and-module-boundaries.md | 63 ---- ...e-init-registry-and-identity-foundation.md | 60 ---- ...parsing-validation-and-details-contract.md | 65 ---- ...can-list-assets-and-studio-read-adapter.md | 61 ---- ...-preview-apply-and-studio-write-adapter.md | 78 ----- ...octor-diagnostics-and-safe-fix-baseline.md | 60 ---- ...an-determinism-and-cache-key-foundation.md | 62 ---- ...sets-pa-and-companion-artifact-emission.md | 63 ---- ...ress-and-studio-operational-integration.md | 83 ----- ...ng-migration-trust-and-production-gates.md | 70 ----- ...e-snapshot-authority-and-durable-commit.md | 194 ------------ ...ace-removal-before-runtime-service-wave.md | 74 ----- ...d-event-bus-and-packer-composition-root.md | 73 ----- ...ntime-core-snapshot-model-and-lifecycle.md | 68 ---- ...15-snapshot-backed-asset-query-services.md | 70 ----- ...mand-completion-and-used-write-services.md | 71 ----- ...dapter-and-assets-workspace-consumption.md | 73 ----- ...ice-retirement-and-regression-hardening.md | 66 ---- ...t-model-separation-and-public-read-dtos.md | 98 ------ ...apabilities-and-register-first-delivery.md | 101 ------ ...ory-snapshot-updates-after-write-commit.md | 77 ----- ...firmation-and-fs-first-manifest-removal.md | 77 ----- ...t-action-wizard-and-fs-first-relocation.md | 101 ------ ...t-file-cache-hydration-and-walker-reuse.md | 200 ------------ .../PR-25-asset-cache-model-and-repository.md | 76 ----- ...alker-cache-input-and-comparison-policy.md | 71 ----- ...untime-walkresult-and-cache-integration.md | 88 ------ ...tracts-summary-validation-and-execution.md | 107 ------- ...-adjustments-for-summary-and-validation.md | 93 ------ ...R-30-pack-wizard-summary-snapshot-query.md | 83 ----- ...31-pack-wizard-validation-snapshot-gate.md | 91 ------ ...clarations-with-explicit-index-contract.md | 113 ------- ...pagation-and-runtime-contract-alignment.md | 80 ----- ...nk-diagnostics-and-validation-hardening.md | 75 ----- ...and-runtime-materialization-preparation.md | 69 ---- ...cution-with-frozen-snapshot-and-staging.md | 86 ----- docs/packer/pull-requests/README.md | 57 +--- docs/studio/README.md | 9 +- ...ition-Snapshot-Transfer-to-Details-DTOs.md | 80 ----- ...-Asset-Bank-Composition-Base-Components.md | 87 ------ ...03-Asset-Bank-Composition-Section-Shell.md | 77 ----- ...mposition-Middleware-and-Staged-Editing.md | 92 ------ ...nk-Composition-WorkspaceBus-Interaction.md | 94 ------ ...on-Persistence-and-Snapshot-Propagation.md | 98 ------ ...a - Dual List and Capacity Meter Agenda.md | 234 -------------- .../Pack Wizard in Assets Workspace Agenda.md | 282 ----------------- docs/studio/agendas/README.md | 9 +- ...nk Composition Base Components Decision.md | 110 ------- ...osition Details DTO Projection Decision.md | 109 ------- ... Middleware and Staged Editing Decision.md | 114 ------- ...tence and Snapshot Propagation Decision.md | 120 ------- ...Bank Composition Section Shell Decision.md | 85 ----- ...ition WorkspaceBus Interaction Decision.md | 110 ------- ...ack Wizard in Assets Workspace Decision.md | 179 ----------- docs/studio/decisions/README.md | 13 +- docs/studio/learn/README.md | 6 +- .../learn/assets-workspace-execution-wave.md | 88 ++++++ docs/studio/learn/bank-composition-editor.md | 126 ++++++++ docs/studio/learn/pack-wizard-shell.md | 87 ++++++ .../project-scoped-state-and-activity.md | 57 ++++ ...-workspace-foundation-and-service-state.md | 71 ----- ...-navigator-search-filters-and-selection.md | 72 ----- ...cted-asset-details-contract-and-preview.md | 80 ----- ...-activity-progress-and-logs-integration.md | 63 ---- ...sets-staged-mutations-preview-and-apply.md | 75 ----- ...d-studio-state-and-activity-persistence.md | 111 ------- ...event-topology-and-lifecycle-foundation.md | 124 -------- ...b-asset-navigator-and-row-subscriptions.md | 75 ----- ...PR-07c-asset-details-and-form-lifecycle.md | 82 ----- ...ation-and-structural-sync-orchestration.md | 83 ----- ...efactor-cleanup-and-regression-coverage.md | 74 ----- ...kage-boundaries-and-local-subscriptions.md | 117 ------- ...9-asset-move-action-and-relocate-wizard.md | 164 ---------- ...bank-composition-details-dto-projection.md | 81 ----- ...PR-10b-bank-composition-base-components.md | 75 ----- ...tion-shell-and-form-session-integration.md | 70 ----- ...family-policies-and-section-coordinator.md | 77 ----- ...spacebus-events-and-local-orchestration.md | 70 ----- ...ply-through-packer-and-snapshot-refresh.md | 76 ----- ...d-shell-and-packer-contract-consumption.md | 166 ---------- docs/studio/pull-requests/README.md | 42 +-- 98 files changed, 824 insertions(+), 8449 deletions(-) delete mode 100644 docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md delete mode 100644 docs/packer/agendas/Tile Bank Packing Materialization Agenda.md delete mode 100644 docs/packer/decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md delete mode 100644 docs/packer/decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md delete mode 100644 docs/packer/decisions/Metadata Convergence to AssetEntry.metadata Decision.md delete mode 100644 docs/packer/decisions/Pack Wizard Pack Execution Semantics Decision.md delete mode 100644 docs/packer/decisions/Pack Wizard Summary and Validation Contracts Decision.md delete mode 100644 docs/packer/decisions/Tile Bank Packing Materialization Decision.md create mode 100644 docs/packer/learn/foundations-workspace-runtime-and-build.md create mode 100644 docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md create mode 100644 docs/packer/learn/runtime-ownership-and-studio-boundary.md create mode 100644 docs/packer/learn/tile-bank-packing-contract.md delete mode 100644 docs/packer/pull-requests/PR-01-packer-project-bootstrap-and-module-boundaries.md delete mode 100644 docs/packer/pull-requests/PR-02-workspace-init-registry-and-identity-foundation.md delete mode 100644 docs/packer/pull-requests/PR-03-asset-declaration-parsing-validation-and-details-contract.md delete mode 100644 docs/packer/pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md delete mode 100644 docs/packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md delete mode 100644 docs/packer/pull-requests/PR-06-doctor-diagnostics-and-safe-fix-baseline.md delete mode 100644 docs/packer/pull-requests/PR-07-build-plan-determinism-and-cache-key-foundation.md delete mode 100644 docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md delete mode 100644 docs/packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md delete mode 100644 docs/packer/pull-requests/PR-10-versioning-migration-trust-and-production-gates.md delete mode 100644 docs/packer/pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md delete mode 100644 docs/packer/pull-requests/PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md delete mode 100644 docs/packer/pull-requests/PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md delete mode 100644 docs/packer/pull-requests/PR-14-project-runtime-core-snapshot-model-and-lifecycle.md delete mode 100644 docs/packer/pull-requests/PR-15-snapshot-backed-asset-query-services.md delete mode 100644 docs/packer/pull-requests/PR-16-write-lane-command-completion-and-used-write-services.md delete mode 100644 docs/packer/pull-requests/PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md delete mode 100644 docs/packer/pull-requests/PR-18-legacy-service-retirement-and-regression-hardening.md delete mode 100644 docs/packer/pull-requests/PR-19-api-surface-audit-model-separation-and-public-read-dtos.md delete mode 100644 docs/packer/pull-requests/PR-20-asset-action-capabilities-and-register-first-delivery.md delete mode 100644 docs/packer/pull-requests/PR-21-point-in-memory-snapshot-updates-after-write-commit.md delete mode 100644 docs/packer/pull-requests/PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md delete mode 100644 docs/packer/pull-requests/PR-23-move-asset-action-wizard-and-fs-first-relocation.md delete mode 100644 docs/packer/pull-requests/PR-24-asset-file-cache-hydration-and-walker-reuse.md delete mode 100644 docs/packer/pull-requests/PR-25-asset-cache-model-and-repository.md delete mode 100644 docs/packer/pull-requests/PR-26-walker-cache-input-and-comparison-policy.md delete mode 100644 docs/packer/pull-requests/PR-27-runtime-walkresult-and-cache-integration.md delete mode 100644 docs/packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md delete mode 100644 docs/packer/pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md delete mode 100644 docs/packer/pull-requests/PR-30-pack-wizard-summary-snapshot-query.md delete mode 100644 docs/packer/pull-requests/PR-31-pack-wizard-validation-snapshot-gate.md delete mode 100644 docs/packer/pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md delete mode 100644 docs/packer/pull-requests/PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md delete mode 100644 docs/packer/pull-requests/PR-34-tile-bank-diagnostics-and-validation-hardening.md delete mode 100644 docs/packer/pull-requests/PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md delete mode 100644 docs/packer/pull-requests/PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md delete mode 100644 docs/studio/agendas/Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md delete mode 100644 docs/studio/agendas/Agenda-02-Asset-Bank-Composition-Base-Components.md delete mode 100644 docs/studio/agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md delete mode 100644 docs/studio/agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md delete mode 100644 docs/studio/agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md delete mode 100644 docs/studio/agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md delete mode 100644 docs/studio/agendas/Asset Bank Composition Area - Dual List and Capacity Meter Agenda.md delete mode 100644 docs/studio/agendas/Pack Wizard in Assets Workspace Agenda.md delete mode 100644 docs/studio/decisions/Bank Composition Base Components Decision.md delete mode 100644 docs/studio/decisions/Bank Composition Details DTO Projection Decision.md delete mode 100644 docs/studio/decisions/Bank Composition Middleware and Staged Editing Decision.md delete mode 100644 docs/studio/decisions/Bank Composition Persistence and Snapshot Propagation Decision.md delete mode 100644 docs/studio/decisions/Bank Composition Section Shell Decision.md delete mode 100644 docs/studio/decisions/Bank Composition WorkspaceBus Interaction Decision.md delete mode 100644 docs/studio/decisions/Pack Wizard in Assets Workspace Decision.md create mode 100644 docs/studio/learn/assets-workspace-execution-wave.md create mode 100644 docs/studio/learn/bank-composition-editor.md create mode 100644 docs/studio/learn/pack-wizard-shell.md create mode 100644 docs/studio/learn/project-scoped-state-and-activity.md delete mode 100644 docs/studio/pull-requests/PR-05a-assets-workspace-foundation-and-service-state.md delete mode 100644 docs/studio/pull-requests/PR-05b-asset-navigator-search-filters-and-selection.md delete mode 100644 docs/studio/pull-requests/PR-05c-selected-asset-details-contract-and-preview.md delete mode 100644 docs/studio/pull-requests/PR-05d-assets-activity-progress-and-logs-integration.md delete mode 100644 docs/studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md delete mode 100644 docs/studio/pull-requests/PR-06-project-scoped-studio-state-and-activity-persistence.md delete mode 100644 docs/studio/pull-requests/PR-07a-assets-event-topology-and-lifecycle-foundation.md delete mode 100644 docs/studio/pull-requests/PR-07b-asset-navigator-and-row-subscriptions.md delete mode 100644 docs/studio/pull-requests/PR-07c-asset-details-and-form-lifecycle.md delete mode 100644 docs/studio/pull-requests/PR-07d-asset-mutation-and-structural-sync-orchestration.md delete mode 100644 docs/studio/pull-requests/PR-07e-assets-refactor-cleanup-and-regression-coverage.md delete mode 100644 docs/studio/pull-requests/PR-08-assets-workspace-panel-package-boundaries-and-local-subscriptions.md delete mode 100644 docs/studio/pull-requests/PR-09-asset-move-action-and-relocate-wizard.md delete mode 100644 docs/studio/pull-requests/PR-10a-bank-composition-details-dto-projection.md delete mode 100644 docs/studio/pull-requests/PR-10b-bank-composition-base-components.md delete mode 100644 docs/studio/pull-requests/PR-10c-bank-composition-section-shell-and-form-session-integration.md delete mode 100644 docs/studio/pull-requests/PR-10d-bank-composition-family-policies-and-section-coordinator.md delete mode 100644 docs/studio/pull-requests/PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md delete mode 100644 docs/studio/pull-requests/PR-10f-bank-composition-apply-through-packer-and-snapshot-refresh.md delete mode 100644 docs/studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md diff --git a/docs/packer/README.md b/docs/packer/README.md index 5e4c3c22..7b140498 100644 --- a/docs/packer/README.md +++ b/docs/packer/README.md @@ -98,10 +98,15 @@ The preferred packer documentation flow is: - `agendas/` stores currently open questions only. - `decisions/` stores only decisions that still need propagation. -- `pull-requests/` stores execution plans. +- `pull-requests/` stores only execution plans for pending work. - `specs/` stores the normative packer contract. - `learn/` stores teaching-oriented consolidation. -The current packer core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles. +The current packer core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). +At this moment: + +- `agendas/` retains only topics that are still open; +- `decisions/` is empty because the last accepted wave was fully propagated; +- `pull-requests/` is empty because the historical execution wave was absorbed into `learn/`. If implementation exposes a missing architectural choice, stop and return to `agendas/` or `decisions/`. diff --git a/docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md b/docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md deleted file mode 100644 index 246c716e..00000000 --- a/docs/packer/agendas/Pack Wizard Studio Decision Propagation Agenda.md +++ /dev/null @@ -1,295 +0,0 @@ -# Pack Wizard Studio Decision Propagation Agenda - -Status: Open -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Purpose - -Converge the packer-side discussion that still remains open after the first `Pack Wizard` propagation wave: the actual `packing` operation. - -`summary` and `validation` are already closed enough to implement and consume. -What is still unresolved is how `pack execution` should behave as a packer-owned operation when Studio enters the `Packing` and `Result` phases. - -This agenda is therefore about execution semantics, artifact emission, progress visibility, and failure boundaries for `packWorkspace(...)`. - -## Problem - -The repository already closed the Studio shell boundary and the packer-side preflight boundary, but the actual pack execution contract is still underspecified. - -Today the gap is concrete: - -1. Studio already depends on a four-phase wizard: - `Summary`, `Validation`, `Packing`, `Result`; -2. the public packer API already exposes `packWorkspace(...)`; -3. `prometeu-packer-v1` still throws `UnsupportedOperationException` for that operation; -4. the specs define `assets.pa` authority and deterministic ordering, but they do not yet define the operational semantics for emitting that artifact through the Studio-facing service boundary. - -Without this agenda, implementation risks falling into one of these traps: - -- a direct file-write implementation that leaks partial artifacts; -- a Studio-visible progress model that is too vague to support the wizard honestly; -- an execution path that does not clearly separate validation failure from emission failure; -- or a result contract that is too poor for the `Result` phase even if the pack technically succeeds. - -## Context - -The upstream state is now clear enough to isolate the remaining question. - -Already closed: - -- Studio is a shell over packer-owned semantics: - [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md) -- packer-side `summary` and `validation` contracts are accepted: - [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md) -- runtime artifact authority is already normative: - [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- event causality and serialized operation rules are already normative: - [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -Current code context: - -- `getPackWorkspaceSummary(...)` already exists in `FileSystemPackerWorkspaceService`; -- `validatePackWorkspace(...)` already exists in `FileSystemPackerWorkspaceService`; -- `packWorkspace(...)` exists in the public API but is not implemented in `prometeu-packer-v1`; -- the current `PackWorkspaceResult` shape is minimal, but the operational meaning of its fields is not fully closed. - -That means the current decision gap is no longer about whether packing should exist. -It is about what guarantees `packWorkspace(...)` must provide when it starts emitting runtime-facing artifacts. - -## Options - -### Option A - Direct in-place pack with minimal lifecycle semantics - -Implement `packWorkspace(...)` as one serialized write-lane operation that: - -- optionally reruns the validation gate; -- emits `assets.pa` and companion artifacts directly into their final locations; -- publishes a small number of lifecycle events; -- returns one final result DTO with success or failure. - -### Option B - Staged pack transaction with explicit lifecycle phases - -Implement `packWorkspace(...)` as one serialized packer-owned execution flow with explicit internal phases: - -1. gate -2. plan/materialize -3. stage emit -4. commit/promote -5. finalize result - -The operation still appears to Studio as one `packWorkspace(...)` call, but the packer gives stronger semantics: - -- validation is rechecked at execution start; -- emitted files are staged before final promotion; -- final artifact visibility changes only at commit; -- progress events map to meaningful lifecycle boundaries; -- the final result distinguishes validation, emission, and persistence failure classes. - -### Option C - Detached build session abstraction - -Introduce a larger `PackSession`-style model or resumable build-session protocol for packing. - -Studio would create a session, observe step state, and then explicitly finalize or close it. - -## Tradeoffs - -- Option A is the smallest implementation step, but it leaves too many failure and visibility rules implicit. -- Option A also makes it easier to leak partially written artifacts into final paths if the process fails mid-pack. -- Option B fits the existing service boundary while still making artifact visibility and progress semantics explicit. -- Option B also aligns well with the current specs: - serialized writes, causal events, deterministic outputs, and packer-owned truth. -- Option B adds some implementation structure, but that structure corresponds to real operational risk and is not ceremonial. -- Option C could become attractive later if the build system needs cancellation, resume, remote workers, or richer host orchestration. -- Option C is too heavy for the current repository state and would introduce a second interaction model before the first one is stable. - -## Recommendation - -Adopt `Option B`. - -The packer should keep `packWorkspace(...)` as a single public service operation, but internally define and honor explicit execution phases with staged emission and an atomic final visibility boundary. - -### Execution Boundary Recommendation - -`packWorkspace(...)` should be the only first-wave operation that emits build artifacts. - -Rules: - -- it runs through the packer-owned serialized write lane for the project; -- it evaluates the active pack set as `registered + included in build`; -- it must perform an internal gate check before emitting artifacts, even if Studio already ran `validation`; -- it must freeze the execution input set before materialization begins; -- a failing gate returns a terminal result without creating final artifacts. - -This avoids trusting host orchestration timing as if it were a correctness guarantee. - -### Frozen Snapshot Recommendation - -`packWorkspace(...)` should not pack from live filesystem rereads after execution begins. - -Recommended first-wave baseline: - -- the packer creates a frozen pack-execution snapshot before materialization starts; -- that frozen snapshot is derived from the current runtime snapshot but enriches build-relevant walk files with in-memory content bytes; -- content bytes are needed only for: - - registered assets included in build; - - artifact files that actually participate in the current build output; -- non-build assets and non-selected artifact files do not need in-memory content in the pack-execution snapshot; -- the current runtime snapshot model should expose file bytes as optional rather than introducing a second snapshot model in the first wave; -- `PackerRuntimeWalkFile` should therefore carry optional content bytes so the packer can freeze build-relevant inputs without forcing all runtime-backed reads to retain content unnecessarily; -- the family walkers may continue to produce full file probes with bytes loaded during probe processing; -- the variation for runtime versus packing should happen when probe results are exported into the runtime walk projection; -- walker materialization must therefore gain clearer execution context/config so build-focused flows can request content bytes intentionally instead of coupling that behavior to every normal read path. - -This preserves precision without turning the general runtime snapshot into a blanket in-memory mirror of the workspace. - -### Walker Policy Recommendation - -The current walker baseline should remain family-oriented and generalist. - -Recommended first-wave baseline: - -- family walkers continue to discover files relevant to the asset family; -- that family-oriented discovery remains the normal runtime-backed mode; -- packing adds one extra selection layer instead of redefining walker discovery itself; -- the extra selection layer filters the discovered probe results down to the files that actually participate in the current build output; -- the same export layer also decides whether optional content bytes are injected into `PackerRuntimeWalkFile`. - -This means the first-wave split should be: - -1. family-relevant probe discovery in the walkers; -2. export/materialization policy for runtime projection; -3. packing-specific projection filter over discovered probe results; -4. optional byte injection only when the export policy requests it. - -This is intentionally conservative. -It keeps the walkers on known ground and moves the packing-specific behavior into one explicit projection/materialization policy layer. - -Recommended config shape: - -```java -public record PackerRuntimeMaterializationConfig( - PackerWalkMode mode, - Predicate projectionFilter) { - - public static PackerRuntimeMaterializationConfig runtimeDefault() { - return new PackerRuntimeMaterializationConfig(PackerWalkMode.RUNTIME, probe -> true); - } - - public static PackerRuntimeMaterializationConfig packingBuild() { - return new PackerRuntimeMaterializationConfig( - PackerWalkMode.PACKING, - PackerProbePolicies::isIncludedInCurrentBuild); - } -} -``` - -With this baseline: - -- `PackerWalkMode.RUNTIME` means runtime-backed general projection and suppresses optional content bytes during export; -- `PackerWalkMode.PACKING` means packing-focused projection and injects optional content bytes during export; -- `projectionFilter` decides which discovered probe results actually survive into `PackerRuntimeWalkFile`; -- the first-wave packing filter should keep only current-build probe results; -- byte injection behavior is derived from `mode` rather than from a second explicit boolean in the first wave. - -### Emission Recommendation - -Artifact emission should be staged before promotion into final visible locations. - -Recommended first-wave baseline: - -- materialize `assets.pa` and companion artifacts in a staging location owned by the packer operation; -- use `build/.staging//` as the first-wave staging location; -- `` should be one random 20-character alphanumeric identifier; -- if a staging directory collision happens for that identifier, the packer may overwrite that staging directory rather than adding a second collision-resolution protocol in the first wave; -- treat staging output as non-authoritative until commit; -- promote staged files into final `build/` locations only after the operation reaches a coherent success point; -- if emission fails before commit, final artifact locations must remain unchanged from the caller's point of view. - -This is the safest baseline for a filesystem-first packer. -It keeps durable visibility aligned with a packer-owned commit boundary rather than with incidental file-write timing. - -### Progress Recommendation - -Progress should continue to flow through the existing packer event path rather than through a polling-specific result shape. - -The first-wave lifecycle should be observable through summaries and progress updates equivalent to: - -1. `packing_started` -2. `packing_validating` -3. `packing_materializing` -4. `packing_emitting` -5. `packing_finalizing` -6. terminal success or failure - -The exact event kind names can still be finalized in the decision, but the meaning must be explicit enough for Studio to render the `Packing` phase honestly without fake timers or inferred state. - -### Result Recommendation - -The final `PackWorkspaceResult` should stay compact but semantically explicit. - -The primary result summary should expose at least: - -- final status; -- whether validation failed or execution actually began; -- canonical build-relative `assets.pa` artifact reference; -- build-relative companion artifact references when emitted; -- total packed asset count; -- elapsed time in milliseconds. - -The first-wave `Result` phase in Studio does not need a full build report dump, but it does need enough structure to distinguish successful pack, blocked pack, and failed pack after execution started. - -### Failure Recommendation - -The packer should distinguish at least three terminal classes: - -1. validation gate failure before emission; -2. execution or materialization failure during pack generation; -3. persistence or promotion failure while making artifacts final. - -These classes matter because they map directly to the Studio `Result` phase already decided upstream. - -### Build Output Recommendation - -The packer publication boundary for this flow should remain `build/`. - -Recommended first-wave baseline: - -- `packWorkspace(...)` publishes final outputs to `build/`; -- the canonical runtime-facing artifact is `build/assets.pa`; -- the baseline companion artifacts are: - - `build/asset_table.json` - - `build/preload.json` - - `build/asset_table_metadata.json` -- a future shipper may consume those packer outputs together with `program.pbx`; -- the shipper is mentioned here only to keep the boundary explicit, not because it participates in `packWorkspace(...)`. - -This keeps the current domain boundary intact: -the packer publishes build artifacts and the shipper assembles cartridges. - -## Open Questions - -None for the first-wave execution shape. -The remaining work is to convert this agenda into a decision and then propagate the agreed materialization policy into code and specs. - -## Recommendation Summary - -This agenda recommends closing the first-wave `packing` contract as: - -1. one packer-owned `packWorkspace(...)` operation; -2. internally phased and serialized through the project write lane; -3. guarded by a packer-owned validation check at execution start; -4. based on one frozen in-memory execution snapshot for the build-relevant asset bytes; -5. staged under `build/.staging//` before promotion to final artifact visibility in `build/`; -6. observable through causality-preserving progress events; -7. finished with a result that distinguishes blocked, failed, and successful pack outcomes. - -## Next Suggested Step - -Convert this agenda into a `docs/packer` decision focused on `pack execution` semantics and propagation targets. - -That decision should then drive: - -1. one PR for `prometeu-packer-api` result and event-contract adjustments, if needed; -2. one PR for `prometeu-packer-v1` execution, staging, and artifact-promotion behavior; -3. one Studio PR to bind the `Packing` and `Result` phases to the final packer-owned execution contract. diff --git a/docs/packer/agendas/README.md b/docs/packer/agendas/README.md index 73911669..395acdf5 100644 --- a/docs/packer/agendas/README.md +++ b/docs/packer/agendas/README.md @@ -5,11 +5,9 @@ This directory contains active packer discussion agendas. ## Active Agendas 1. [`Tilemap and Metatile Runtime Binary Layout Agenda.md`](./Tilemap%20and%20Metatile%20Runtime%20Binary%20Layout%20Agenda.md) -2. [`Pack Wizard Studio Decision Propagation Agenda.md`](./Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md) -3. [`Tile Bank Packing Materialization Agenda.md`](./Tile%20Bank%20Packing%20Materialization%20Agenda.md) -4. [`Variable Tile Bank Palette Serialization Agenda.md`](./Variable%20Tile%20Bank%20Palette%20Serialization%20Agenda.md) +2. [`Variable Tile Bank Palette Serialization Agenda.md`](./Variable%20Tile%20Bank%20Palette%20Serialization%20Agenda.md) -The first packer agenda wave was consolidated into normative specs under [`../specs/`](../specs/) and didactic material under [`../learn/`](../learn/). +Closed packer agenda waves must be absorbed into [`../specs/`](../specs/) and [`../learn/`](../learn/) instead of remaining here as historical residue. ## Purpose diff --git a/docs/packer/agendas/Tile Bank Packing Materialization Agenda.md b/docs/packer/agendas/Tile Bank Packing Materialization Agenda.md deleted file mode 100644 index b23e0adb..00000000 --- a/docs/packer/agendas/Tile Bank Packing Materialization Agenda.md +++ /dev/null @@ -1,258 +0,0 @@ -# Tile Bank Packing Materialization Agenda - -Status: Open -Domain Owner: `docs/packer` -Cross-Domain Impact: `../runtime`, `docs/studio` - -## Purpose - -Convergir a discussão sobre como um asset `tile bank` deve ser materializado durante o `packing` para produzir payload runtime-facing válido dentro de `assets.pa`. - -Esta agenda não trata do workflow operacional do `Pack Wizard`. -Ela trata do contrato técnico de materialização do formato `TILES/indexed_v1`: - -- quais arquivos entram no pack; -- como eles viram payload binário final; -- quais campos do `asset_table` são derivados; -- quais metadados convergem para `AssetEntry.metadata`; -- e quais invariantes devem falhar o build. - -## Problem - -O repositório já tem base suficiente para: - -1. descobrir arquivos relevantes de `tile bank`; -2. validar metadados mínimos como `tile_size`; -3. construir snapshots runtime-backed; -4. definir `assets.pa` como artefato autoritativo do runtime. - -Mas ainda não existe decisão formal sobre a materialização final de `tile bank` no pack. - -Hoje falta fechar, pelo menos: - -- qual é o payload binário efetivamente emitido para um `tile bank`; -- como múltiplos artifacts selecionados são agregados no payload final; -- como `bank_type`, `codec`, `size`, `decoded_size` e `metadata` são derivados para a entrada runtime; -- quais dados ficam em `AssetEntry.metadata` versus quais permanecem detalhe interno de pipeline; -- quais condições tornam o pack inválido para esse formato. - -Sem isso, o `packWorkspace(...)` pode até ganhar semântica operacional correta, mas ainda ficará sem contrato suficiente para produzir `assets.pa` conformat para `tile bank`. - -## Context - -O contrato upstream já impõe limites claros: - -- `assets.pa` é o artefato runtime-facing autoritativo: - [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md) -- `asset_table` é determinística por `asset_id`, offsets são relativos ao payload region e metadata converge para um sink único: - [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- o runtime espera `assets.pa` autocontido com `asset_table` e `preload` válidos: - [`../../../runtime/docs/runtime/specs/13-cartridge.md`](../../../runtime/docs/runtime/specs/13-cartridge.md) -- o runtime consome `AssetEntry { asset_id, asset_name, bank_type, offset, size, decoded_size, codec, metadata }`: - [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md) - -Contexto atual de código: - -- `PackerAssetWalker` já reconhece `OutputFormatCatalog.TILES_INDEXED_V1`; -- `PackerTileBankWalker` já produz probes/metadata family-relevant; -- o snapshot atual já consegue expor arquivos candidatos e metadata de walk; -- ainda não existe materialização final de payload de `tile bank` dentro de `assets.pa`. - -Consumer baseline now confirmed in `../runtime`: - -- `TILES` now uses `codec = NONE` as the runtime-facing v1 baseline; -- serialized tile pixels are packed `u4` palette indices in payload order; -- the runtime expands those packed indices into one `u8` logical index per pixel in memory after decode; -- tile-bank palettes are serialized as `RGB565` `u16` values in little-endian order; -- runtime-facing v1 uses `64` palettes per tile bank; -- the runtime loader currently requires the following metadata fields for tile banks: - - `tile_size` - - `width` - - `height` - - `palette_count` -- for v1, `palette_count` must be `64`; -- for v1, the serialized tile-bank payload is: - 1. packed indexed pixels for the full sheet, using `ceil(width * height / 2)` bytes; - 2. one palette block of `64 * 16 * 2 = 2048` bytes; -- for v1, the runtime-side size expectations are: - - `size = ceil(width * height / 2) + 2048` - - `decoded_size = (width * height) + 2048` -- for the producer-side contract discussed here, `tile_id = 0` remains valid and must not be reserved away by the packer. - -Relevant confirmed runtime references: - -- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md) -- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md) -- [`../../../runtime/crates/console/prometeu-drivers/src/asset.rs`](../../../runtime/crates/console/prometeu-drivers/src/asset.rs) -- [`../../../runtime/crates/console/prometeu-hal/src/tile_bank.rs`](../../../runtime/crates/console/prometeu-hal/src/tile_bank.rs) -- tilemap empty-cell semantics remain under active runtime discussion and must not currently force the packer to reserve `tile_id = 0`: - [`../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md`](../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md) - -Isso significa que o problema agora não é descoberta de arquivos. -O lado consumidor já está suficientemente claro. -O problema agora é fechar o contrato produtor `tile bank -> runtime asset entry + payload bytes` no packer sem contradizer esse baseline runtime. - -## Options - -### Option A - Concatenate selected tile artifacts as a simple raw stream - -Cada artifact selecionado do `tile bank` vira um segmento binário simples, e o payload final do asset é a concatenação determinística desses segmentos. - -`metadata` carrega apenas o mínimo necessário para o runtime interpretar o asset. - -### Option B - Emit one canonical tile-bank payload plus normalized runtime metadata - -Os artifacts selecionados são primeiro normalizados para um modelo canônico de `tile bank`, e então o packer emite: - -- um único payload binário canônico para o asset; -- um conjunto fechado de campos runtime-facing em `AssetEntry.metadata`. - -Qualquer detalhe interno adicional de pipeline fica fora do contrato runtime principal ou vai apenas para tooling metadata. - -### Option C - Preserve rich per-artifact structure directly in runtime metadata - -O packer mantém estrutura mais rica de artifacts individuais no próprio `AssetEntry.metadata`, expondo para o runtime detalhes mais próximos da pipeline de build. - -## Tradeoffs - -- Option A é a implementação mais simples, mas corre risco de deixar semântica demais implícita no consumidor. -- Option A também pode dificultar compatibilidade futura se a concatenação simples não codificar claramente limites, forma lógica ou derivação de `decoded_size`. -- Option B exige fechar um modelo canônico do `tile bank`, mas produz o contrato mais limpo entre packer e runtime. -- Option B também respeita melhor a regra já vigente de convergência para `AssetEntry.metadata` sem transformar metadata runtime em espelho da pipeline. -- Option C pode parecer flexível no curto prazo, mas mistura detalhe de pipeline com contrato runtime e aumenta acoplamento. -- Option C tensiona diretamente o guardrail já documentado de que `asset_table[].metadata` não deve virar depósito arbitrário de estrutura interna. - -## Recommendation - -Adotar `Option B`. - -O primeiro formato de packing a ser fechado deve ter payload canônico e metadata runtime-facing normalizada. - -### Payload Recommendation - -O `tile bank` deve produzir um payload binário único por asset incluído no build. - -Regras recomendadas: - -- o payload é derivado apenas dos artifacts selecionados que realmente entram no build atual; -- a ordem de agregação dos artifacts deve ser determinística by `artifacts[*].index`; -- for v1, `1 artifact = 1 tile`; -- for the current target, the canonical tile-bank sheet is always `256 x 256`; -- tile placement inside that fixed sheet is row-major; -- `tile_id` is the linear row-major slot and therefore matches the normalized `artifacts[*].index`; -- resulting capacity is therefore: - - `tile_size = 8` -> `32 x 32 = 1024` tiles - - `tile_size = 16` -> `16 x 16 = 256` tiles - - `tile_size = 32` -> `8 x 8 = 64` tiles -- o payload final do asset deve ter fronteiras e interpretação definidas pelo próprio contrato do formato, não por convenção incidental de concatenação; -- para `TILES/indexed_v1`, o payload v1 já deve assumir: - 1. plano de pixels packed `u4`; - 2. bloco de paletas `64 * 16 * u16`; -- palettes must always be materialized to `RGB565` during pack emission; -- `size` deve representar o tamanho emitido no payload region; -- `decoded_size` deve seguir a convenção runtime já confirmada: - tamanho expandido dos indices em memória mais o bloco de paletas runtime-facing. - -### Runtime Entry Recommendation - -Cada `tile bank` emitido para o runtime deve preencher, no mínimo: - -- `asset_id` -- `asset_name` -- `bank_type = TILES` -- `offset` -- `size` -- `decoded_size` -- `codec` -- `metadata` - -O contrato de `bank_type`, `codec` e `decoded_size` não deve ser deixado implícito no packer implementation detail. - -Baseline now fixed by the runtime consumer: - -- `bank_type = TILES` -- `codec = NONE` -- metadata mínima obrigatória: - - `tile_size` - - `width` - - `height` - - `palette_count = 64` -- `width` and `height` are bank-sheet helpers, not per-artifact dimensions -- with the current v1 target, the emitted bank sheet is fixed at `256 x 256` -- producer-side metadata normalization must emit what the consumer requires while preserving segmented authoring meaning: - - `asset.json.output.metadata` -> `AssetEntry.metadata` - - `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec` - - `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline` - -### Metadata Recommendation - -`AssetEntry.metadata` deve receber apenas os campos runtime-consumable e format-relevant. - -Direção inicial recomendada: - -- metadados declarativos como `tile_size` entram no sink runtime; -- metadados derivados necessários para leitura correta do runtime entram no sink runtime, pelo menos: - - `width` - - `height` - - `palette_count`; -- `AssetEntry.metadata` should aggregate normalized maps using this structure: - - `asset.json.output.metadata` -> `metadata` - - `asset.json.output.codec_configuration` -> `metadata.codec` - - `asset.json.output.pipeline` -> `metadata.pipeline` -- bank palettes are declared in `asset.json.output.pipeline.palettes` using explicit `{ index, palette }` entries and emitted in ascending numeric `index` order; -- any tile in the bank may be rendered with any palette in the bank; -- palette assignment is therefore not a per-artifact packing contract and remains a runtime draw-time concern; -- the packer must nevertheless validate whether the declared bank palette set safely covers the indices used by packed tiles. -- detalhes de pipeline úteis apenas para inspeção e tooling não devem dominar `AssetEntry.metadata`; -- quando um detalhe interno for necessário apenas para tooling, ele deve preferir companion tooling data em vez de inflar o contrato runtime. - -### Failure Recommendation - -O build de `tile bank` deve falhar quando qualquer uma das seguintes condições acontecer: - -1. não existir conjunto suficiente de artifacts selecionados para materialização válida; -2. o metadata declarativo obrigatório do formato estiver ausente ou inválido; -3. a normalização dos artifacts para o payload canônico falhar; -4. houver colisão ou ambiguidade ao convergir metadata runtime-facing; -5. o packer não conseguir derivar de forma determinística os campos exigidos para a entry runtime. - -Additional first-wave diagnostic expectations: - -- duplicate `artifacts[*].index` is `blocking`; -- gap in normalized `artifacts[*].index` ordering is `blocking`; -- sheet-capacity overflow for the fixed `256 x 256` target is `blocking`; -- bank without declared palettes in `asset.json.output.pipeline.palettes` is `blocking`; -- declared palette list above `64` is `blocking`; -- malformed palette declarations are `blocking`; -- tiles that use fragile indices, meaning indices not represented safely across the full declared bank palette set, emit a `WARNING`; -- that fragile-index warning is advisory in the first wave and does not block pack by itself unless later promoted by decision. - -### Packing Boundary Recommendation - -O seletor de packing para `tile bank` deve operar sobre os probes já descobertos pelo walker family-oriented. - -Regras: - -- o walker continua generalista e orientado à family; -- a seleção do que entra no payload final acontece na policy/materialization layer de packing; -- somente probes do asset registrado, incluído no build, e efetivamente selecionados pelo contrato do formato entram na materialização final; -- quando o `PackerRuntimeMaterializationConfig` estiver em `PACKING`, esses probes relevantes devem carregar bytes opcionais preenchidos para congelar o input do pack. -- palette declarations in `asset.json.output.pipeline.palettes` carry explicit semantic identity through `index`; -- palette order is ascending numeric `index`, never raw array position; -- palette ids are the normalized declared `index` values from that pipeline palette list; -- all tiles in the bank may use any palette declared in the bank; -- palette selection is a runtime draw concern, not a tile-payload embedding concern. - -## Open Questions - -1. None at this stage for the tile-bank v1 producer contract. - -## Expected Follow-up - -1. Converter esta agenda em uma `decision` de `docs/packer` para materialização de `tile bank`. -2. Propagar o contrato resultante para: - - `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md` - - specs runtime relevantes em `../runtime` -3. Planejar PR de implementação do materializador de `tile bank` em `prometeu-packer-v1`. -4. Adicionar testes de conformance do formato: - `artifacts -> payload -> asset_table entry -> runtime-read assumptions`. diff --git a/docs/packer/decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md b/docs/packer/decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md deleted file mode 100644 index 3c2e0a53..00000000 --- a/docs/packer/decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md +++ /dev/null @@ -1,130 +0,0 @@ -# Concurrency, Observability, and Studio Adapter Boundary Decision - -Status: Accepted -Date: 2026-03-11 -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Context - -The production `prometeu-packer` track introduces two architectural seams that must not remain implicit: - -1. the packer will become the operational source of truth for asset summaries, diagnostics, mutation previews, and build lifecycle state; -2. Studio will consume that operational model through adapters instead of reconstructing packer semantics locally; -3. the event and concurrency model must stay coherent when the packer is integrated into the Studio `Assets` workspace and shell. - -Without an explicit decision, the repository risks drifting into duplicated semantics: - -- Studio deriving packer-facing summaries from filesystem heuristics; -- Studio inventing lifecycle meaning not present in packer events; -- concurrent mutation or build behavior becoming observable in inconsistent ways. - -## Decision - -The following direction is adopted: - -1. `prometeu-packer` is the semantic owner of asset operational state. -2. Studio is a consumer and remapper of packer responses and events, not a competing source of packer truth. -3. The baseline packer write policy is a `single-writer semantic lane per project`. -4. Packer observability is packer-native and causality-preserving. -5. Studio adapters may reshape packer data for UI presentation, but may not invent packer semantics, causal relationships, or final outcomes absent from packer responses/events. - -## Adopted Constraints - -### 1. Summary and Response Authority - -- asset `summary`, `details`, `diagnostics`, `preview`, and build/mutation lifecycle state originate in the packer; -- Studio may use packer responses directly or remap them into view models; -- Studio must not define an alternative packer summary model from direct filesystem inspection once the packer-backed path exists; -- UI-oriented phrasing or grouping is allowed only as a remapping of packer-owned semantics. - -### 2. Concurrency Model - -- coordination is project-scoped; -- unrelated projects are not forced into one global execution lane; -- `read/read` may run concurrently when reads observe a coherent snapshot; -- `read/write` must not expose torn intermediate state; -- `write/write` on the same project is serialized; -- `build/write` on the same project is serialized unless a future explicit transactional model supersedes this baseline; -- preview generation may run outside the final commit-critical section when safe, but final apply/commit remains serialized. - -### 3. Event and Observability Model - -- the packer emits the authoritative event stream for asset operations; -- each logical operation must carry a stable `operation_id`; -- events within one operation must carry monotonic `sequence`; -- baseline event payloads must preserve fields equivalent to: - - `project_id` - - `operation_id` - - `sequence` - - `kind` - - `timestamp` - - `summary` - - `progress` when applicable - - `affected_assets` when applicable -- event ordering must remain causally coherent for one operation; -- progress-like low-value repetition may be coalesced by sinks/adapters; -- terminal lifecycle markers must remain individually observable. - -### 4. Studio Adapter Boundary - -- Studio adapts packer events into the existing Studio event bus and workspace models; -- Studio may convert packer-native envelopes into Studio-native event types for shell/workspace consumption; -- that adapter layer must remain translational, not semantic-authoritative; -- Activity, progress, and staged mutation surfaces in Studio must reflect packer-native lifecycle, not replace it. - -## Why This Direction Was Chosen - -- It prevents split-brain semantics between packer and Studio. -- It keeps packer behavior testable outside JavaFX. -- It allows Studio UI iteration without moving domain rules into the UI layer. -- It gives concurrency and observability one owner, which is necessary for deterministic mutation and build behavior. - -## Explicit Non-Decisions - -This decision does not define: - -- the final internal threading primitives or executor topology of `prometeu-packer`; -- a watch daemon or continuous background worker model; -- remote/shared cache coordination; -- cross-project scheduling policy beyond allowing separate projects to coordinate independently; -- final event transport beyond the local adapter/event sink model currently planned. - -## Implications - -- read adapters belong in the packer integration track, not in Studio-local filesystem services; -- mutation preview/apply semantics belong in packer services and only map into Studio staged UI models; -- Studio Activity and progress integration must preserve packer causality metadata, even if the UI renders a simplified form; -- tests must verify both same-project write serialization and event ordering through the Studio adapter path. - -## Propagation Targets - -Specs: - -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -Plans: - -- [`../pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md`](../pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md) -- [`../pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](../pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md) -- [`../pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md`](../pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md) - -Cross-domain references: - -- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) -- [`../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md`](../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md) - -Implementation surfaces: - -- future `prometeu-packer` service contracts and event sink abstractions -- Studio packer read/write/event adapters -- Studio Activity/progress mapping code - -## Validation Notes - -The decision is correctly implemented only when all of the following are true: - -- the same packer operation can be replayed and observed without Studio inventing hidden state; -- conflicting writes on one project cannot commit concurrently; -- Activity/progress in Studio can be driven from packer-native events alone; -- Studio summaries are either direct packer outputs or remapped packer outputs, never independent semantic recomputation. diff --git a/docs/packer/decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md b/docs/packer/decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md deleted file mode 100644 index 78f9ffa2..00000000 --- a/docs/packer/decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md +++ /dev/null @@ -1,175 +0,0 @@ -# Filesystem-First Operational Runtime and Reconcile Boundary Decision - -Status: Accepted -Date: 2026-03-15 -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Context - -The current packer model already has the right core separation: - -- `assets/.prometeu/index.json` is the authoritative registry/catalog for managed assets; -- each asset root is anchored by `asset.json`; -- `asset.json` is the authoring-side declaration of how that asset is packed; -- Studio is meant to consume packer-owned operational semantics instead of recreating them locally. - -What is still missing is a clear architectural decision for how the packer should behave operationally at runtime. - -The repository now needs an answer to these questions: - -1. should the packer remain a collection of direct filesystem services, recomputing state per request; -2. should the packer become a pure database-style system that displaces the open filesystem workflow; -3. or should it become a filesystem-first operational runtime that maintains an in-memory snapshot while preserving the workspace as the durable authoring surface. - -The wrong answer here would create product friction. - -If the packer behaves like a pure database, it will fight the real creative workflow where developers: - -- edit files with their preferred tools; -- move directories manually when needed; -- inspect and version workspace files directly; -- expect the Studio to help organize work, not imprison it. - -At the same time, if the packer stays purely filesystem-per-call, it will remain too expensive, too incoherent under concurrent use, and too weak as the operational source of truth for Studio. - -## Decision - -The following direction is adopted: - -1. `prometeu-packer` remains `filesystem-first`. -2. The packer becomes a `project-scoped operational runtime`, not a pure database. -3. The packer maintains an in-memory project snapshot for live operational reads and write coordination. -4. The durable authoring workspace on disk remains the final persisted source of truth. -5. The packer owns request/response read and write APIs over that runtime snapshot. -6. Writes execute through a packer-owned project write lane and become durably visible only after commit succeeds. -7. The packer will support background divergence detection between runtime snapshot and filesystem state. -8. Divergence detection must surface reconcile state explicitly; it must not silently invent or hide semantic repairs. -9. Studio remains a frontend consumer of packer responses, commands, and events. -10. When embedded inside Studio, the packer runtime is bootstrapped with a typed event bus reference supplied by the Studio bootstrap container. - -## Adopted Constraints - -### 1. Filesystem-First Authority - -- the asset workspace under `assets/` remains the authoring environment; -- `asset.json` remains the asset-local declaration contract; -- `assets/.prometeu/index.json` remains the authoritative registry/catalog for managed assets; -- the packer runtime snapshot is an operational projection of packer-owned workspace artifacts, not a replacement authoring format. - -### 2. Identity and Declaration Split - -- `asset_id`, `included_in_build`, and registry-managed location tracking remain registry/catalog concerns; -- `asset.json` remains primarily a declaration of the asset contract and packing inputs/outputs; -- `asset.json` may carry the asset-local identity anchor needed for reconcile, specifically `asset_uuid`; -- `asset.json` must not become a dumping ground for transient UI state, cache state, or catalog-derived bookkeeping that belongs in `index.json` or other packer-owned control files. - -### 3. Snapshot-Backed Read Semantics - -- normal read APIs should serve from a coherent in-memory project snapshot; -- the packer must not require a full workspace recomputation for every normal read call once the runtime is active; -- concurrent reads may proceed when they observe a coherent snapshot generation; -- reads must not expose torn intermediate write state as committed truth. - -### 4. Packer-Owned Write Execution - -- write operations on one project are coordinated by the packer, not by caller timing; -- the baseline policy remains a single-writer semantic lane per project; -- write intent may compute previews before final commit when safe; -- final apply/commit remains serialized per project; -- successful durable commit defines post-write visibility. - -### 5. Durable Commit Boundary - -- the packer runtime may stage write changes in memory before disk commit; -- partially applied intermediate state must not be presented as durably committed truth; -- commit failure must leave the project in an explicitly diagnosable condition; -- recovery and reconcile rules must be designed as packer behavior, not delegated to Studio guesswork. - -### 6. Divergence Detection and Reconcile - -- a future packer-owned background observation path may detect divergence between runtime snapshot and filesystem state; -- this path exists to keep the runtime honest with respect to manual or external edits; -- divergence must result in explicit runtime state such as stale, diverged, reconciling, or failed; -- the packer must not silently rewrite user content just because divergence was observed; -- reconcile is an explicit packer-owned behavior and must preserve causality in events and responses. - -### 7. Studio Consumer Boundary - -- Studio consumes packer read responses, write outcomes, and packer-native lifecycle events; -- Studio may render stale/diverged/reconciling states, but must not invent packer-side reconcile semantics; -- Studio must not become the owner of filesystem-vs-snapshot conflict resolution; -- the Studio integration contract should remain command-oriented and event-driven. - -### 8. Embedded Event Bus Bootstrap - -- when the packer is embedded inside Studio, it must receive a typed event bus reference during bootstrap instead of creating an unrelated local event system; -- that reference is used for packer event publication and any packer-side subscription/unsubscription behavior needed by the embedded runtime; -- in Studio, the owner of that typed event bus reference is the application container; -- the Studio `Container` must be initialized as part of Studio boot before packer-backed workspaces or adapters start consuming packer services. - -## Why This Direction Was Chosen - -- It preserves the developer's open creative workflow around normal files and directories. -- It keeps the packer useful as an organizing and coordinating system instead of turning it into an opaque silo. -- It allows fast and coherent reads for Studio and tooling. -- It gives write coordination, commit visibility, and operational causality one owner. -- It creates a realistic path toward future background divergence detection without pretending that the filesystem stopped mattering. - -## Explicit Non-Decisions - -This decision does not define: - -- the final class/module names of the packer runtime implementation; -- the final executor/thread primitive used internally; -- the exact event vocabulary for all future reconcile states; -- the final automatic-vs-manual reconcile policy for each drift scenario; -- a watch-service or daemon transport implementation; -- remote or multi-process synchronization; -- a pure database persistence model. - -## Implications - -- the packer runtime track must preserve `index.json` plus `asset.json` as the durable workspace artifacts; -- `asset.json` should evolve carefully to support local identity anchoring without absorbing catalog-only fields; -- the runtime snapshot should be described as an operational cache/projection with authority for live service behavior, not as a new authoring truth; -- mutation, doctor, build, and read services should converge on the same runtime state model; -- future drift detection work must be designed together with diagnostics, refresh, and reconcile surfaces in Studio. -- embedded Studio wiring must preserve one container-owned typed event bus reference instead of fragmented packer-local bus ownership. - -## Propagation Targets - -Specs: - -- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) -- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md) - -Plans: - -- [`../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](../pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md) - -Cross-domain references: - -- [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) - -Implementation surfaces: - -- future packer project-runtime/bootstrap code -- snapshot-backed read services -- project write-lane and durable commit pipeline -- drift detection and reconcile state reporting -- Studio packer adapters for stale/diverged/reconciling operational states -- Studio bootstrap/container wiring for the shared typed event bus reference - -## Validation Notes - -This decision is correctly implemented only when all of the following are true: - -- developers may continue to inspect and edit asset workspace files directly; -- packer reads are coherent without requiring full recomputation on each normal request; -- same-project writes remain serialized by the packer; -- Studio does not observe torn committed truth during write activity; -- divergence between runtime snapshot and filesystem state can be detected and surfaced explicitly; -- Studio remains a consumer of packer-owned reconcile and lifecycle semantics rather than inventing them. diff --git a/docs/packer/decisions/Metadata Convergence to AssetEntry.metadata Decision.md b/docs/packer/decisions/Metadata Convergence to AssetEntry.metadata Decision.md deleted file mode 100644 index c7b604a0..00000000 --- a/docs/packer/decisions/Metadata Convergence to AssetEntry.metadata Decision.md +++ /dev/null @@ -1,146 +0,0 @@ -# Metadata Convergence to AssetEntry.metadata Decision - -Status: Accepted -Date: 2026-03-17 -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/vm-arch`, runtime asset consumers - -## Context - -The packer asset contract currently has multiple metadata-producing sources with different responsibilities: - -- asset-level runtime contract metadata (authoring declaration); -- codec-related metadata (codec configuration/effective codec parameters); -- pipeline-derived metadata generated during build materialization (for example, indexed ranges for packed samples). - -At runtime, consumers read one metadata sink from the asset table: `AssetEntry.metadata`. - -Without an explicit decision, the system risks inconsistent behavior and documentation drift: - -- metadata spread across sources without deterministic merge semantics; -- ambiguity between storage-layout fields (`AssetEntry.offset`/`AssetEntry.size`) and pipeline-internal indexing data (`offset`/`length` per sample); -- Studio, packer, and runtime docs diverging on where runtime consumers should read final values. - -## Decision - -The following direction is adopted: - -1. All runtime-consumable metadata must converge to a single sink: `AssetEntry.metadata`. -2. Source segmentation in `asset.json` is allowed for authoring clarity, but build materialization must normalize these sources into that single sink. -3. Metadata normalization must be deterministic and testable. -4. `AssetEntry.offset` and `AssetEntry.size` remain payload slicing fields and are not reinterpreted as pipeline-internal indexing metadata. -5. Pipeline indexing metadata (for example, audio per-`sample_id` ranges) must live inside `AssetEntry.metadata` under explicit keys. - -## Adopted Constraints - -### 1. Source Segmentation vs Runtime Sink - -- authoring sources may remain segmented (asset metadata, codec metadata, pipeline metadata); -- runtime consumers must read effective values from `AssetEntry.metadata`; -- packer build output is responsible for normalization. - -### 2. Deterministic Convergence - -- normalization must produce the same `AssetEntry.metadata` for the same effective declaration and build inputs; -- metadata key collisions between independent sources must be rejected with a build-time error unless explicitly specified by family/format contract; -- normalization order and collision policy must be documented by packer specs. - -### 3. Audio Indexing Semantics - -For multi-sample audio banks, sample indexing metadata belongs to `AssetEntry.metadata`, keyed by `sample_id`. - -Illustrative shape: - -```json -{ - "metadata": { - "sample_rate": 22050, - "channels": 1, - "samples": { - "1": { "offset": 0, "length": 100 } - }, - "codec": { - "parity": 10 - } - } -} -``` - -This decision accepts either nested codec metadata (for example `metadata.codec.*`) or a flat equivalent only when the family/format spec declares that shape explicitly. - -### 4. Offset Ambiguity Guardrail - -- `AssetEntry.offset`/`AssetEntry.size` describe where one packed asset payload is stored in `assets.pa`; -- `metadata.samples[*].offset`/`metadata.samples[*].length` describe internal layout/indexing inside that asset's runtime payload contract; -- documentation and tests must keep these meanings separate. - -## Why This Direction Was Chosen - -- It keeps runtime consumption simple: one metadata sink. -- It preserves authoring ergonomics: source metadata can stay segmented by concern. -- It avoids semantic duplication between packer and runtime consumers. -- It creates a clear path for bank-like assets (tiles/audio) that require indexed internal metadata. - -## Explicit Non-Decisions - -This decision does not define: - -- the final complete metadata schema for every asset family; -- the final canonical codec metadata shape (`nested` vs `flat`) for all formats; -- multi-sample audio runtime loading implementation details; -- exact binary container/header layout for audio banks. - -## Implications - -- packer specs must define normalization semantics and collision policy; -- packer build/materialization must emit normalized metadata into `AssetEntry.metadata`; -- runtime-facing docs must state that effective metadata is read from `AssetEntry.metadata`; -- tests must cover convergence correctness and ambiguity boundaries for offset semantics. - -## Propagation Targets - -Specs: - -- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- [`../../vm-arch/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md) - -Plans: - -- next packer PR/plan that introduces metadata normalization and multi-source merge validation - -Code: - -- packer asset declaration/materialization pipeline -- asset table emission path (`AssetEntry.metadata` payload) - -Tests: - -- normalization unit tests (source merge determinism) -- collision/ambiguity tests for offset semantics -- regression tests for runtime-readable metadata shape - -Docs: - -- packer specs and learn artifacts covering metadata source-to-sink flow -- runtime asset-management documentation referencing `AssetEntry.metadata` as sink - -## References - -Related specs: - -- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) - -Related agendas: - -- no formal agenda artifact yet for this specific topic; this decision consolidates current packer/runtime alignment discussion. - -## Validation Notes - -This decision is correctly implemented only when all of the following are true: - -- runtime consumers can read final effective metadata exclusively from `AssetEntry.metadata`; -- segmented metadata sources in authoring inputs converge deterministically during packing; -- offset semantics remain unambiguous between asset-table payload slicing and pipeline-internal indexing; -- documentation across packer and runtime-facing domains is consistent about this source-to-sink contract. \ No newline at end of file diff --git a/docs/packer/decisions/Pack Wizard Pack Execution Semantics Decision.md b/docs/packer/decisions/Pack Wizard Pack Execution Semantics Decision.md deleted file mode 100644 index cfaddd1b..00000000 --- a/docs/packer/decisions/Pack Wizard Pack Execution Semantics Decision.md +++ /dev/null @@ -1,218 +0,0 @@ -# Pack Wizard Pack Execution Semantics Decision - -Status: Accepted -Date: 2026-03-20 -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Context - -The Studio-side `Pack Wizard` flow is already closed as a shell over packer-owned operations. - -On the packer side, the repository also already closed the first-wave `summary` and `validation` contracts. - -What remained open was the execution contract for the actual pack operation: - -- how `packWorkspace(...)` should behave when Studio enters `Packing` and `Result`; -- how the packer should avoid filesystem drift while packing; -- how final artifact visibility should be protected during emission; -- and how the operation should report success, blocking failure, and execution failure without pushing semantic reconstruction into Studio. - -The agenda that closed this discussion is: - -- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md) - -Relevant upstream references are: - -- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md) -- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md) -- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md) - -## Decision - -The first-wave packer execution contract for the `Pack Wizard` adopts the following direction: - -1. `packWorkspace(...)` is one packer-owned public operation. -2. It executes through the project-scoped serialized write lane. -3. It must rerun a packer-owned gate check before artifact emission begins. -4. It must pack from one frozen execution snapshot rather than from live filesystem rereads. -5. It must stage emitted outputs before promotion to final `build/` locations. -6. It publishes final build artifacts to `build/` only after a coherent success point is reached. -7. It remains the only first-wave operation that emits build artifacts for the Studio `Pack Wizard`. - -## Adopted Constraints - -### 1. Execution Boundary - -- `packWorkspace(...)` evaluates the active pack set as `registered + included in build`; -- it runs under the same packer-owned project write serialization model already adopted for same-project writes and build operations; -- it must not trust Studio call ordering as if that were a correctness guarantee; -- a failing pack gate returns a terminal result without publishing final build artifacts. - -### 2. Frozen Execution Snapshot - -- pack execution must not reread live workspace files once execution materialization begins; -- the packer must create a frozen pack-execution snapshot before payload materialization starts; -- that frozen snapshot is derived from the current runtime snapshot and packer-owned walk/materialization path; -- file content bytes are required only for build-relevant inputs: - - registered assets included in build; - - artifact files that actually participate in the current build output; -- non-build assets and non-selected artifact files do not need in-memory content in the pack-execution snapshot. - -### 3. Runtime Walk Projection Shape - -- the existing runtime walk projection model remains the baseline; -- `PackerRuntimeWalkFile` gains optional content bytes instead of introducing a second snapshot model in the first wave; -- optional content bytes remain absent in normal runtime-backed projection and become present only in packing-focused projection. - -### 4. Materialization Policy Shape - -The adopted first-wave shape is: - -```java -public record PackerRuntimeMaterializationConfig( - PackerWalkMode mode, - Predicate projectionFilter) { - - public static PackerRuntimeMaterializationConfig runtimeDefault() { - return new PackerRuntimeMaterializationConfig(PackerWalkMode.RUNTIME, probe -> true); - } - - public static PackerRuntimeMaterializationConfig packingBuild() { - return new PackerRuntimeMaterializationConfig( - PackerWalkMode.PACKING, - PackerProbePolicies::isIncludedInCurrentBuild); - } -} -``` - -With this contract: - -- `PackerWalkMode.RUNTIME` suppresses optional content bytes during export to runtime walk projection; -- `PackerWalkMode.PACKING` injects optional content bytes during export to runtime walk projection; -- `projectionFilter` decides which discovered probe results survive into `PackerRuntimeWalkFile`; -- the first-wave packing filter keeps only current-build probe results. - -### 5. Walker Boundary - -- family walkers remain family-oriented discovery mechanisms; -- they may continue to produce full file probes with bytes available during probe processing; -- the runtime-versus-packing variation happens during export/materialization into runtime walk projection; -- packing-specific selection is one additional projection/materialization policy layer over the discovered probe results; -- first-wave pack execution must not fork the repository into one discovery model for runtime and another discovery model for packing. - -### 6. Staging and Promotion Boundary - -- pack execution stages outputs under `build/.staging//`; -- `` is one random 20-character alphanumeric identifier; -- if a staging directory collision occurs for that identifier, the packer may overwrite that staging directory in the first wave; -- staged outputs are non-authoritative until promotion; -- promotion into final `build/` locations happens only after the operation reaches a coherent success point; -- if emission fails before promotion, final `build/` outputs must remain unchanged from the caller's point of view. - -### 7. Build Publication Boundary - -- the canonical runtime-facing output is `build/assets.pa`; -- the baseline companion outputs are: - - `build/asset_table.json` - - `build/preload.json` - - `build/asset_table_metadata.json` -- `packWorkspace(...)` stops at build artifact publication; -- shipper behavior remains outside this operation and is mentioned only as a future consumer boundary. - -### 8. Result and Failure Semantics - -The final pack result must distinguish at least: - -1. validation gate failure before emission; -2. execution or materialization failure during pack generation; -3. persistence or promotion failure while making outputs final. - -The first-wave result summary must expose at least: - -- final status; -- whether execution actually began or stopped at gate failure; -- canonical build-relative reference to `assets.pa`; -- build-relative companion artifact references when emitted; -- total packed asset count; -- elapsed time in milliseconds. - -### 9. Minimum Structural Conformance - -The first-wave pack execution is not successful unless the emitted outputs satisfy the already adopted baseline structural guarantees: - -- `asset_table` ordering is deterministic by increasing `asset_id`; -- header serialization is canonical; -- offsets are relative to `payload_offset`; -- preload entries are resolved by `asset_id`; -- invalid preload references or preload slot clashes fail the operation rather than being deferred to host guesswork. - -## Why This Direction Was Chosen - -- It preserves packer ownership of build semantics while keeping Studio as an honest shell. -- It prevents filesystem drift during execution without turning the general runtime snapshot into a wasteful full-memory mirror. -- It aligns build visibility with the same commit-oriented operational model already adopted elsewhere in the packer runtime. -- It keeps the first-wave implementation on known terrain by reusing current walker/materialization structure instead of inventing a second discovery stack. -- It gives the Studio enough structured outcome information to render `Packing` and `Result` without semantic reconstruction. - -## Explicit Non-Decisions - -This decision does not yet define: - -- the format-specific payload materialization rules for each asset output format; -- the canonical payload contract for `tile bank`, `sound bank`, or other family-specific outputs; -- the final event kind vocabulary for pack execution progress beyond requiring causality-preserving observable lifecycle; -- cancellation semantics; -- future incremental or remote build behavior; -- shipper packaging rules, cartridge manifest generation, or final packaged cartridge layout. - -## Implications - -- `packWorkspace(...)` can no longer be implemented as a direct live-filesystem read/write shortcut; -- runtime walk projection and materialization code must gain explicit packing-aware export policy; -- `PackerRuntimeWalkFile` must support optional content bytes; -- pack execution implementation must include frozen-input creation, staging, promotion, and structured terminal outcomes; -- format-specific packing discussions must now happen as follow-up decisions rather than being guessed inside the generic execution path. - -## Propagation Targets - -Specs: - -- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -Plans: - -- [`../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md) -- [`../pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](../pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md) -- future packer PR for pack execution, staging, and result semantics - -Cross-domain references: - -- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md) -- [`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md) - -Follow-up agenda references: - -- [`../agendas/Tile Bank Packing Materialization Agenda.md`](../agendas/Tile%20Bank%20Packing%20Materialization%20Agenda.md) - -Implementation surfaces: - -- `prometeu-packer-api` pack execution result contract -- `prometeu-packer-v1` runtime materialization/export policy -- `prometeu-packer-v1` frozen execution snapshot creation -- `prometeu-packer-v1` staging and promote pipeline -- Studio `Pack Wizard` packing/result bindings - -## Validation Notes - -This decision is correctly implemented only when all of the following are true: - -- `packWorkspace(...)` does not depend on live filesystem rereads after frozen execution materialization begins; -- only build-relevant selected inputs carry frozen content bytes into the packing path; -- normal runtime-backed reads do not retain optional content bytes by default; -- failed execution before promotion does not leave partial final `build/` artifacts presented as success; -- successful pack publication produces `build/assets.pa` and the expected companion outputs coherently; -- Studio can distinguish blocked, failed, and successful pack outcomes from packer-owned results alone. diff --git a/docs/packer/decisions/Pack Wizard Summary and Validation Contracts Decision.md b/docs/packer/decisions/Pack Wizard Summary and Validation Contracts Decision.md deleted file mode 100644 index 81da6e4c..00000000 --- a/docs/packer/decisions/Pack Wizard Summary and Validation Contracts Decision.md +++ /dev/null @@ -1,174 +0,0 @@ -# Pack Wizard Summary and Validation Contracts Decision - -Status: Accepted -Date: 2026-03-20 -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Context - -The Studio `Pack Wizard` flow is now closed on the host side as a shell over packer-owned operations. - -That decision already fixed the outer boundary: - -- Studio is the shell; -- packer owns summary, validation, pack execution, progress, and result semantics; -- the wizard flow is phase-based; -- the active pack set is the current `registered + included in build` set. - -On the packer side, the first remaining need is to close the public contract for `summary` and `validation` before the repository moves deeper into pack execution semantics. - -This decision consolidates the `summary` and `validation` part of the packer-side discussion from: - -- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md) -- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md) - -The main question is not whether Studio should have these phases. -That is already settled. -The question is what the packer must expose as the authoritative public contract for those phases. - -## Decision - -The packer public contract for the `Pack Wizard` first wave adopts the following direction: - -1. `summary` and `validation` are distinct packer operations; -2. both operations are read-only and non-mutating; -3. both operations evaluate the same pack set: - `registered + included in build`; -4. both operations are packer-owned and snapshot-backed; -5. Studio consumes these packer responses and must not reconstruct equivalent semantics locally. - -## Adopted Constraints - -### 1. Summary Boundary - -- `summary` is a fast snapshot-backed preflight view; -- `summary` must return from packer-owned snapshot state, not from a deep recomputation pass; -- `summary` is not a build preview and must not imply that artifacts were emitted; -- `summary` must not anticipate companion artifacts or emitted artifact details in the first wave; -- `summary` must not include unregistered assets or excluded assets as explicit summary items. - -### 2. Summary Shape - -The first-wave `summary` contract contains: - -1. one aggregate count for the active pack set; -2. one per-asset list for the active pack set. - -The aggregate is intentionally minimal in the first wave: - -- total included asset count is sufficient. - -Each per-asset summary entry must expose: - -- `assetId` -- `assetName` -- `assetFamily` -- `minArtifactCount` -- `maxArtifactCount` -- `lastModified` - -`lastModified` is required in the public contract even if early implementations temporarily expose `0` until the real value is fully available per asset. - -The per-asset summary list is the intended payload for Studio-side graphical occupancy presentation. -The aggregate remains deliberately small. - -### 3. Validation Boundary - -- `validation` evaluates the same active pack set as `summary`; -- `validation` is read-only and non-mutating; -- `validation` is snapshot-backed; -- `validation` may internally reuse deep-inspection or reconcile-grade logic where needed; -- a future Studio flow may add an explicit deep-sync step before validation, but validation itself still evaluates the packer snapshot boundary. - -### 4. Validation Failure Rule - -Only diagnostics marked `blocking` fail validation in the first wave. - -The rule is: - -- if no blocking diagnostics are returned for the active pack set, validation is green; -- if any blocking diagnostics are returned for the active pack set, validation is red and packing must not begin. - -Warnings and non-blocking diagnostics are not part of the first-wave validation gate contract. - -### 5. Validation Shape - -The primary validation payload is the per-asset diagnostics list. - -Aggregate validation data may still exist, but it is secondary. -The Studio may derive aggregate visual summaries from the per-asset list if useful. - -Each per-asset validation entry must expose: - -- `assetId` -- `assetName` -- `assetPath` -- `lastModified` -- `diagnostics` - -In the first wave, `diagnostics` in this contract means blocking diagnostics only. - -Ordering is not a packer responsibility in the first-wave validation payload. -The Studio may sort the returned list as needed for presentation. - -## Why This Direction Was Chosen - -- It keeps `summary` and `validation` aligned with the existing request/result API style instead of inventing a special build-session protocol too early. -- It keeps ownership where it belongs: the packer remains the source of truth for pack-set semantics and validation outcomes. -- It gives Studio enough structured data to render the preflight and validation phases without recreating packer meaning. -- It keeps the first-wave contract intentionally narrow so the repository can close `summary` and `validation` without prematurely locking the heavier `pack execution` semantics. -- It gives the Studio enough per-asset detail to show useful occupancy and blocker views while keeping ordering and higher-level UI grouping on the host side. - -## Explicit Non-Decisions - -This decision does not yet define: - -- the final `pack execution` request/result contract; -- emitted artifact reporting rules beyond what is already upstream in packer artifact specs; -- the final event vocabulary for pack progress; -- whether future validation payloads should include non-blocking diagnostics; -- the final source for real `lastModified` values in every asset case; -- runtime-ingestion and cartridge-facing conformance gates for actual artifact emission. - -## Implications - -- the current public API work for pack summary must expand beyond aggregate-only shape; -- the current public API work for validation must expand beyond generic aggregate-first DTOs; -- Studio `Pack Wizard` binding should evolve toward the per-asset summary and per-asset validation payloads defined here; -- `summary` and `validation` can now be implemented independently of the heavier pack execution discussion; -- the next packer discussion wave should focus primarily on execution semantics, artifact emission guarantees, and runtime/cartridge ingestion conformance. - -## Propagation Targets - -Specs: - -- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -Plans: - -- [`../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md) - -Cross-domain references: - -- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md) -- [`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md) - -Implementation surfaces: - -- `prometeu-packer-api` summary and validation request/result DTOs -- snapshot-backed pack summary query logic -- snapshot-backed pack validation logic -- Studio pack wizard summary and validation bindings - -## Validation Notes - -This decision is correctly implemented only when all of the following are true: - -- `summary` returns quickly from packer-owned snapshot state; -- Studio does not reconstruct pack summary from navigator rows or local UI state; -- `summary` returns only active pack-set items, not excluded or unregistered items; -- `validation` returns blocking-diagnostic information per asset for the same active pack set; -- a returned validation payload with any blocking diagnostics stops the wizard before pack execution; -- the Studio may reorder the returned lists without changing packer semantics. diff --git a/docs/packer/decisions/README.md b/docs/packer/decisions/README.md index 2a9d5bb5..64e73b83 100644 --- a/docs/packer/decisions/README.md +++ b/docs/packer/decisions/README.md @@ -1,17 +1,12 @@ # Packer Decisions -This directory contains packer decision records. +This directory contains packer decision records that still need propagation. -Retained packer decision records: +Current retained set: -- [`Concurrency, Observability, and Studio Adapter Boundary Decision.md`](./Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md) -- [`Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](./Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md) -- [`Metadata Convergence to AssetEntry.metadata Decision.md`](./Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md) -- [`Pack Wizard Summary and Validation Contracts Decision.md`](./Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md) -- [`Pack Wizard Pack Execution Semantics Decision.md`](./Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md) -- [`Tile Bank Packing Materialization Decision.md`](./Tile%20Bank%20Packing%20Materialization%20Decision.md) +- none -The first packer decision wave was already consolidated into: +The current packer decision wave has already been consolidated into: - normative specifications under [`../specs/`](../specs/) - didactic material under [`../learn/`](../learn/) diff --git a/docs/packer/decisions/Tile Bank Packing Materialization Decision.md b/docs/packer/decisions/Tile Bank Packing Materialization Decision.md deleted file mode 100644 index 83d57652..00000000 --- a/docs/packer/decisions/Tile Bank Packing Materialization Decision.md +++ /dev/null @@ -1,211 +0,0 @@ -# Tile Bank Packing Materialization Decision - -Status: Accepted -Date: 2026-03-20 -Domain Owner: `docs/packer` -Cross-Domain Impact: `../runtime`, `docs/studio` - -## Context - -The packer execution contract for `packWorkspace(...)` is already closed. - -What remained open for `tile bank` was the format-specific producer contract: - -- which selected files become part of the packed asset; -- how those files become the canonical `TILES/indexed_v1` payload; -- how `AssetEntry` fields are derived for runtime consumption; -- how bank palettes are declared and normalized; -- which diagnostics block the build for this format. - -The agenda that closed this discussion is: - -- [`../agendas/Tile Bank Packing Materialization Agenda.md`](../agendas/Tile%20Bank%20Packing%20Materialization%20Agenda.md) - -Relevant upstream references are: - -- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md) -- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- [`../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md`](../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md) -- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md) -- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md) -- [`../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md`](../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md) - -## Decision - -The first-wave packer materialization contract for `tile bank` adopts the following direction: - -1. `TILES/indexed_v1` emits one canonical payload per asset. -2. `1 artifact = 1 tile` in the first wave. -3. Artifacts are ordered by normalized `artifacts[*].index`. -4. Tile placement is row-major in one fixed `256 x 256` sheet. -5. `tile_id` is the linear row-major slot and therefore matches the normalized artifact index. -6. Tile pixels are serialized as packed `u4` indices. -7. Bank palettes are serialized as `RGB565` `u16` values. -8. Palette declarations use explicit semantic identity through `{ index, palette }`. -9. `AssetEntry.metadata` keeps required runtime fields readable at the root while preserving segmented codec and pipeline subtrees. -10. Format-structural diagnostics are raised in the walker/materialization path and therefore participate in validation before pack execution reruns the gate. - -## Adopted Constraints - -### 1. Canonical Payload Shape - -- the payload is produced from build-selected artifacts only; -- the payload is the canonical bank sheet raster, not a concatenation of per-artifact binary fragments; -- for `TILES/indexed_v1`, the serialized payload shape is: - 1. packed `u4` pixel indices for the full emitted sheet; - 2. one palette block of `64 * 16 * 2` bytes; -- palettes are always materialized to `RGB565` during pack emission; -- the producer-side payload contract is aligned to what the runtime loader already requires. - -### 2. Artifact-to-Tile Contract - -- `1 artifact = 1 tile` in v1; -- artifacts are normalized by `artifacts[*].index`; -- `tile_id = artifacts[*].index` after normalization; -- the canonical emitted sheet is always `256 x 256`; -- placement is row-major within that fixed sheet. - -Resulting tile capacities: - -- `tile_size = 8` -> `32 x 32 = 1024` tiles -- `tile_size = 16` -> `16 x 16 = 256` tiles -- `tile_size = 32` -> `8 x 8 = 64` tiles - -### 3. Runtime Entry Contract - -Each emitted `tile bank` runtime entry must populate: - -- `asset_id` -- `asset_name` -- `bank_type = TILES` -- `offset` -- `size` -- `decoded_size` -- `codec = NONE` -- `metadata` - -For v1: - -- `size = ceil(width * height / 2) + 2048` -- `decoded_size = (width * height) + 2048` -- `width = 256` -- `height = 256` -- `palette_count = 64` - -### 4. Palette Contract - -- bank palettes are declared in `asset.json.output.pipeline.palettes`; -- each palette declaration must use explicit shape `{ index, palette }`; -- semantic ordering is ascending numeric `index`, never raw array position; -- palette ids are the normalized declared `index` values; -- any tile in the bank may be rendered with any palette in the bank; -- palette choice is a runtime draw-time concern and is not embedded per tile in the packed payload. - -### 5. Metadata Normalization Contract - -`AssetEntry.metadata` keeps runtime-required fields readable while preserving authoring segmentation: - -- `asset.json.output.metadata` -> `AssetEntry.metadata` -- `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec` -- `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline` - -For tile-bank v1 this means: - -- `tile_size`, `width`, `height`, and `palette_count` remain directly readable at the metadata root; -- codec-specific data is nested under `metadata.codec`; -- pipeline-derived data is nested under `metadata.pipeline`. - -This packer decision intentionally aligns with the runtime-side follow-up agenda rather than flattening everything into one ambiguous map. - -### 6. Diagnostics and Failure Semantics - -The following conditions are blocking for tile-bank v1: - -- duplicate `artifacts[*].index` -- gaps in normalized `artifacts[*].index` -- fixed-sheet capacity overflow -- bank without declared palettes -- palette declaration count above `64` -- malformed palette declarations -- missing or invalid required format metadata -- any failure to normalize artifacts into one deterministic payload - -The following condition is warning-only in the first wave: - -- fragile tile indices, meaning tile indices that are not safely represented across the full declared bank palette set - -### 7. Walker and Validation Boundary - -- family walkers remain discovery-oriented; -- tile-bank structural diagnostics must be produced in the walker/materialization path; -- validation consumes those diagnostics naturally; -- pack execution reruns the validation gate on a newly created frozen execution snapshot before materialization begins. - -## Why This Direction Was Chosen - -- It matches the runtime consumer contract instead of inventing a producer-local interpretation. -- It keeps `tile bank` payload semantics explicit and deterministic. -- It avoids embedding per-artifact or per-draw palette assignment into the packed bytes. -- It preserves stable palette identity through explicit `index` declarations. -- It keeps validation early without weakening the pack-time rerun gate. -- It gives the runtime a metadata shape that is readable and still semantically segmented. - -## Explicit Non-Decisions - -This decision does not yet define: - -- future support for `1 artifact -> many tiles`; -- non-`256 x 256` tile-bank targets; -- alternative tile-bank codecs beyond `NONE`; -- future palette compaction or palette-id remapping strategies; -- the runtime-side final decision for general `AssetEntry.metadata` normalization helpers; -- future sprite or tilemap semantic adjustments unrelated to packer-owned payload production. - -## Implications - -- tile-bank packing implementation must materialize a full sheet raster rather than artifact fragments; -- tile-bank payload generation must pack `u4` indices explicitly in the packer; -- palette declarations and palette overhauling flows must preserve explicit palette `index`; -- runtime-entry metadata emission must preserve both root-required fields and segmented nested maps; -- tile-bank validation logic belongs in the walker/materialization path and must be reused by pack execution gate reruns. - -## Propagation Targets - -Specs: - -- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) - -Plans: - -- [`../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md`](../pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md) -- future packer PR for tile-bank payload materialization -- future packer PR for tile-bank validation diagnostics - -Cross-domain references: - -- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md) -- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md) -- [`../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md`](../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md) -- [`../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md`](../../../runtime/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md) - -Implementation surfaces: - -- `prometeu-packer-v1` tile-bank payload materializer -- `prometeu-packer-v1` tile-bank diagnostics in walker/materialization path -- `prometeu-packer-v1` metadata convergence for `AssetEntry` -- Studio tile-bank authoring and inspection surfaces that expose palettes or bank composition - -## Validation Notes - -This decision is correctly implemented only when all of the following are true: - -- artifact normalization produces one deterministic row-major `256 x 256` bank sheet; -- emitted tile ids match normalized artifact indices; -- emitted pixel bytes are packed as `u4`; -- emitted palette bytes are `RGB565` `u16`; -- palette declarations are read and written by explicit `index`; -- runtime-required metadata fields remain readable at the root; -- codec and pipeline metadata survive under `metadata.codec` and `metadata.pipeline`; -- structural blockers are visible during validation and are rerun by pack execution before emission. diff --git a/docs/packer/learn/README.md b/docs/packer/learn/README.md index 5042ab04..2f8e225b 100644 --- a/docs/packer/learn/README.md +++ b/docs/packer/learn/README.md @@ -52,4 +52,8 @@ Start here: 1. [`mental-model-packer.md`](./mental-model-packer.md) 2. [`mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md) -3. [`mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md) +3. [`foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md) +4. [`runtime-ownership-and-studio-boundary.md`](./runtime-ownership-and-studio-boundary.md) +5. [`mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md) +6. [`pack-wizard-summary-validation-and-pack-execution.md`](./pack-wizard-summary-validation-and-pack-execution.md) +7. [`tile-bank-packing-contract.md`](./tile-bank-packing-contract.md) diff --git a/docs/packer/learn/foundations-workspace-runtime-and-build.md b/docs/packer/learn/foundations-workspace-runtime-and-build.md new file mode 100644 index 00000000..f384b38a --- /dev/null +++ b/docs/packer/learn/foundations-workspace-runtime-and-build.md @@ -0,0 +1,91 @@ +# Foundations: Workspace, Runtime, and Build + +## Original Problem + +The packer domain accumulated a long implementation wave covering workspace control, asset identity, scanning, mutations, diagnostics, deterministic planning, runtime snapshots, and cache reuse. + +The historical PR chain was useful while the repository was converging, but it stopped being a good onboarding surface: + +- too much knowledge was spread across execution slices; +- too much reasoning depended on chronological reconstruction; +- too little of that knowledge was available as one stable mental model. + +## Consolidated Decision + +The stable packer foundation is: + +1. the workspace stays open and filesystem-first; +2. `assets/.prometeu/index.json` owns managed identity and inclusion state; +3. each asset root is anchored by `asset.json`; +4. the packer runtime serves coherent snapshot-backed reads; +5. writes are coordinated by the packer and become visible after durable commit; +6. build outputs are derived deterministically from validated, packer-owned state. + +## Final Model + +### 1. Workspace and Identity + +- `asset_id` is the stable managed identifier used for ordering, inclusion, and runtime-facing tables; +- `asset_uuid` is the local identity anchor that helps reconcile the same logical asset across path movement; +- `asset_name` is the logical human-facing identifier and is not a substitute for managed identity; +- `asset.json` describes authoring intent, not registry-owned bookkeeping. + +### 2. Read and Write Authority + +- normal reads come from a coherent runtime snapshot rather than from ad hoc filesystem scans; +- the filesystem still matters because it remains the durable authoring surface; +- writes flow through packer-owned preview/apply semantics and one project-scoped serialized lane. + +### 3. Deterministic Build Path + +- only validated managed assets enter the build path; +- asset ordering is deterministic by increasing `asset_id`; +- runtime-facing artifacts are emitted from canonical packer-owned planning and materialization rules; +- companion artifacts mirror build authority rather than define parallel truth. + +### 4. Runtime Snapshot Evolution + +The later runtime wave refined the first foundation: + +- runtime state became explicitly project-scoped; +- snapshot updates happen after successful write commit; +- query services read from that runtime state; +- cache layers exist to accelerate the same ownership model, not to bypass it. + +## Examples + +### Example: Why relocation does not create a new asset + +If an asset root moves on disk, the packer should preserve the managed identity when the move is a relocation of the same logical asset. + +That is why: + +- the registry owns stable managed identity; +- path is mutable operational state; +- relocation updates root tracking without inventing a new `asset_id`. + +### Example: Why filesystem order cannot define build order + +Two equivalent workspaces may be traversed in different directory order. +The build must still emit the same `asset_table` and payload layout. + +That is why deterministic ordering is tied to managed identity, not traversal order. + +## Common Pitfalls and Anti-Patterns + +- Treating `asset_name` as if it were a stable runtime identifier. +- Moving registry-owned fields into `asset.json`. +- Recomputing semantic read models directly from Studio-side filesystem heuristics. +- Letting build order depend on traversal order, cache insertion order, or UI ordering. +- Treating cache state as semantic authority instead of as an optimization. + +## References + +- Specs: + - [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md) + - [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) + - [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) + - [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) +- Related learn: + - [`./mental-model-packer.md`](./mental-model-packer.md) + - [`./mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md) diff --git a/docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md b/docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md index 99fc3c03..b4777a20 100644 --- a/docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md +++ b/docs/packer/learn/mental-model-metadata-convergence-and-runtime-sink.md @@ -24,10 +24,6 @@ The accepted direction is: 4. collisions require explicit contract rules or must fail build; 5. `AssetEntry.offset`/`AssetEntry.size` keep payload slicing semantics and do not replace internal pipeline indexing. -Decision reference: - -- [`../decisions/Metadata Convergence to AssetEntry.metadata Decision.md`](../decisions/Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md) - ## Final Model Think in two layers: @@ -77,6 +73,6 @@ In this model: ## References -- Decision: [`../decisions/Metadata Convergence to AssetEntry.metadata Decision.md`](../decisions/Metadata%20Convergence%20to%20AssetEntry.metadata%20Decision.md) - Spec: [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -- Spec: [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) \ No newline at end of file +- Spec: [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) +- Related learn: [`./tile-bank-packing-contract.md`](./tile-bank-packing-contract.md) diff --git a/docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md b/docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md new file mode 100644 index 00000000..a92304d3 --- /dev/null +++ b/docs/packer/learn/pack-wizard-summary-validation-and-pack-execution.md @@ -0,0 +1,118 @@ +# Pack Wizard: Summary, Validation, and Pack Execution + +## Original Problem + +The Studio-side wizard was already accepted as a shell over packer-owned operations, but the packer side still needed one coherent story for: + +1. what `summary` means; +2. what `validation` means; +3. how `packWorkspace(...)` executes without trusting stale UI state or live filesystem rereads. + +The historical agenda, decisions, and PRs solved this in slices. +This document keeps the final model in one place. + +## Consolidated Decision + +The first-wave `Pack Wizard` contract is phase-based and fully packer-owned: + +1. `summary` is a fast snapshot-backed preflight view; +2. `validation` is a snapshot-backed gate over the same active pack set; +3. `packWorkspace(...)` is the only artifact-emitting wizard operation; +4. execution reruns the gate on a fresh frozen snapshot; +5. outputs are staged before promotion into final `build/` locations. + +The active pack set is always: + +`registered + included in build` + +## Final Model + +### 1. Summary + +`summary` is not a build preview. +It is a quick packer-owned view of the current active pack set. + +First-wave payload: + +- total included asset count; +- one per-asset list with: + - `assetId` + - `assetName` + - `assetFamily` + - `minArtifactCount` + - `maxArtifactCount` + - `lastModified` + +### 2. Validation + +`validation` evaluates the same pack set as `summary`, but its job is to answer a different question: + +Can packing begin? + +First-wave rule: + +- only `blocking` diagnostics fail validation; +- warnings are visible elsewhere, but they are not part of the first validation gate contract. + +Primary payload: + +- one per-asset list containing only assets with blocking diagnostics. + +### 3. Pack Execution + +`packWorkspace(...)` is a write-lane operation. +It does not trust that earlier summary or validation responses are still current. + +The first-wave execution path is: + +1. create a fresh execution snapshot; +2. rerun the gate on that snapshot; +3. materialize outputs from frozen in-memory inputs; +4. write to `build/.staging//`; +5. promote to final `build/` outputs only after coherent success. + +### 4. Result Semantics + +The final result must distinguish: + +- gate failure before emission; +- execution/materialization failure; +- persistence/promotion failure; +- successful publication. + +Studio should be able to render `Packing` and `Result` from packer-owned outcome semantics alone. + +## Examples + +### Example: Why green validation is not enough + +Validation may have been green a few seconds earlier. +If the workspace changes before pack execution begins, the packer still must rerun the gate on a fresh frozen snapshot. + +That protects the operation from: + +- stale UI assumptions; +- filesystem drift; +- accidental emission from no-longer-valid inputs. + +### Example: Why summary excludes unregistered assets + +The wizard is a pack-set workflow, not a generic workspace inspection screen. +Unregistered or excluded assets may matter to other tooling, but they are not explicit summary items in the first-wave wizard contract. + +## Common Pitfalls and Anti-Patterns + +- Treating `summary` as if it were an emitted-artifact preview. +- Running validation over a broader set than `registered + included in build`. +- Letting non-blocking warnings fail the first-wave validation gate. +- Reading live filesystem bytes after frozen execution materialization has started. +- Publishing final `build/` outputs before the operation has reached a coherent success point. + +## References + +- Specs: + - [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) + - [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) +- Cross-domain: + - [`../../studio/learn/pack-wizard-shell.md`](../../studio/learn/pack-wizard-shell.md) + - [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) diff --git a/docs/packer/learn/runtime-ownership-and-studio-boundary.md b/docs/packer/learn/runtime-ownership-and-studio-boundary.md new file mode 100644 index 00000000..7b27ff9e --- /dev/null +++ b/docs/packer/learn/runtime-ownership-and-studio-boundary.md @@ -0,0 +1,88 @@ +# Runtime Ownership and Studio Boundary + +## Original Problem + +Once the packer stopped being just a set of direct filesystem helpers, the repository needed a clear answer for three things: + +1. who owns operational asset semantics; +2. how concurrent reads and writes stay coherent; +3. how Studio consumes packer state without duplicating domain logic. + +Without that boundary, the system would drift into split-brain behavior between packer services and Studio UI code. + +## Consolidated Decision + +The packer is the semantic owner of operational asset state. +Studio is a consumer of packer responses, commands, and events. + +The stable boundary is: + +- filesystem-first authoring workspace; +- project-scoped runtime snapshot for reads; +- single-writer semantic lane per project for commit-bearing operations; +- packer-native observability with causal ordering; +- Studio adapters that translate for presentation but do not invent semantics. + +## Final Model + +### 1. Filesystem-First Runtime + +- the workspace on disk remains the durable source of truth; +- the runtime snapshot is an operational projection used for coherent reads and write coordination; +- divergence between runtime state and filesystem state must become explicit packer state, not silent repair. + +### 2. Concurrency Model + +- `read/read` may run concurrently when both observe one coherent snapshot; +- `read/write` must not expose torn intermediate state; +- `write/write` on the same project is serialized; +- build-bearing operations share the same project-scoped coordination story. + +### 3. Event Ownership + +- packer events are authoritative for lifecycle, progress, and outcomes; +- each logical operation carries stable causality through `operation_id` and monotonic `sequence`; +- sinks may coalesce noisy progress updates, but terminal lifecycle events remain observable. + +### 4. Studio Adapter Rule + +- Studio may remap packer data into workspace and shell view models; +- Studio must not recreate packer summaries, mutation semantics, or reconcile semantics from local heuristics; +- adapter code is translational, not semantic-authoritative. + +## Examples + +### Example: Mutation preview in Studio + +The preview may be rendered in Studio-specific components, but the semantic meaning of: + +- blockers, +- warnings, +- registry mutations, +- filesystem mutations, +- final apply outcome + +must still come from the packer. + +### Example: Activity and progress + +If the UI shows a simplified progress bar or activity feed, that is fine. +What is not fine is for Studio to infer a successful final outcome without a packer-native terminal event or response. + +## Common Pitfalls and Anti-Patterns + +- Rebuilding packer summaries from navigator rows or local filesystem scans. +- Treating adapter code as a second owner of mutation or reconcile rules. +- Hiding divergence by silently refreshing state without surfacing the transition. +- Allowing same-project writes to race because the caller "already validated" earlier. +- Collapsing event causality into UI-local state that cannot be replayed or tested outside Studio. + +## References + +- Specs: + - [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) + - [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) +- Cross-domain: + - [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) +- Related learn: + - [`./foundations-workspace-runtime-and-build.md`](./foundations-workspace-runtime-and-build.md) diff --git a/docs/packer/learn/tile-bank-packing-contract.md b/docs/packer/learn/tile-bank-packing-contract.md new file mode 100644 index 00000000..ba204c26 --- /dev/null +++ b/docs/packer/learn/tile-bank-packing-contract.md @@ -0,0 +1,116 @@ +# Tile Bank Packing Contract + +## Original Problem + +After the generic pack execution boundary was closed, `tile bank` still lacked one explicit producer contract. + +The repository needed to settle: + +1. how selected tile artifacts become one packed payload; +2. how palette identity is declared and normalized; +3. which runtime fields are derived for `AssetEntry`; +4. which structural problems block packing before byte emission. + +## Consolidated Decision + +The first-wave `tile bank` producer contract is: + +1. one canonical `TILES/indexed_v1` payload per asset; +2. `1 artifact = 1 tile`; +3. artifacts are normalized by explicit `artifacts[*].index`; +4. the emitted sheet is fixed at `256 x 256` and row-major; +5. tile pixels are packed `u4`; +6. bank palettes are emitted as `RGB565` `u16`; +7. palette declarations use explicit `{ index, palette }`; +8. structural diagnostics are produced early in walker/materialization and therefore participate in validation. + +## Final Model + +### 1. Payload Shape + +The payload is not a concatenation of artifact-local binaries. +It is one canonical bank raster: + +1. packed `u4` pixel indices for the full sheet; +2. one `64 * 16 * 2` palette block. + +### 2. Artifact and Tile Identity + +- artifacts are normalized by ascending declared `index`; +- `tile_id` matches the normalized artifact index; +- placement is row-major in the fixed sheet; +- v1 capacities depend on `tile_size`: + - `8 -> 1024` + - `16 -> 256` + - `32 -> 64` + +### 3. Palette Contract + +- palette identity is semantic, not positional; +- ordering is ascending numeric `index`, never raw list order; +- any tile may be rendered with any bank palette at runtime; +- palette selection is a draw-time concern, not an embedded per-tile payload field. + +### 4. Metadata Contract + +`AssetEntry.metadata` keeps runtime-required fields readable at the root while preserving segmented subtrees: + +- `output.metadata -> metadata` +- `output.codec_configuration -> metadata.codec` +- `output.pipeline -> metadata.pipeline` + +For tile banks, that means root readability for values such as: + +- `tile_size` +- `width` +- `height` +- `palette_count` + +### 5. Validation Boundary + +Tile-bank structural issues belong in the walker/materialization path, not in a late pack-only surprise phase. + +Blocking conditions include: + +- duplicate artifact indices; +- gaps in normalized artifact indices; +- fixed-sheet overflow; +- missing palettes; +- palette count above `64`; +- malformed palette declarations; +- missing required metadata; +- normalization failure. + +Fragile tile indices are warnings in the first wave, not blockers by themselves. + +## Examples + +### Example: Why palette index must be explicit + +If palette identity depends on array position, a harmless editorial reorder can silently change runtime meaning. + +Using `{ index, palette }` makes semantic identity reviewable and stable. + +### Example: Why validation must see tile-bank structure early + +If duplicate artifact indices are discovered only during final byte emission, the wizard reaches `Packing` too late. +The correct behavior is for validation to surface the blocker before emission begins, and for pack execution to rerun that same gate on a fresh execution snapshot. + +## Common Pitfalls and Anti-Patterns + +- Treating artifact declaration order as semantic tile identity. +- Packing per-artifact fragments instead of one canonical sheet. +- Embedding palette choice per tile in the packed payload. +- Flattening all metadata into one ambiguous map. +- Discovering tile-bank blockers only during late byte emission. + +## References + +- Specs: + - [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) + - [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) +- Cross-domain: + - [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md) + - [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md) +- Related learn: + - [`./mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md) diff --git a/docs/packer/pull-requests/PR-01-packer-project-bootstrap-and-module-boundaries.md b/docs/packer/pull-requests/PR-01-packer-project-bootstrap-and-module-boundaries.md deleted file mode 100644 index 1976df9e..00000000 --- a/docs/packer/pull-requests/PR-01-packer-project-bootstrap-and-module-boundaries.md +++ /dev/null @@ -1,63 +0,0 @@ -# PR-01 Packer Project Bootstrap and Module Boundaries - -Domain Owner: `docs/packer` - -## Briefing - -Create the standalone `prometeu-packer` project and establish the production module boundaries required by the packer specs. - -This PR starts the implementation track without leaking packer behavior into Studio. - -## Objective - -Deliver a separate top-level `prometeu-packer` project with build wiring, package boundaries, test harness, and service-facing contracts that future PRs can implement incrementally. - -## Dependencies - -- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -## Scope - -- add `prometeu-packer` as a separate project in the repository build -- define the baseline package/module layout for: - - workspace and registry services - - declaration parsing and validation - - mutation preview/apply services - - build planning and artifact emission - - diagnostics and event reporting -- define the public service contracts that Studio may consume through adapters -- add baseline unit-test and fixture support for packer-only development - -## Non-Goals - -- no full workspace semantics yet -- no asset build emission yet -- no Studio UI changes beyond dependency wiring preparation - -## Execution Method - -1. Add `prometeu-packer` to Gradle settings and repository build wiring. -2. Create baseline package namespaces and service interfaces. -3. Establish a packer-owned test fixture layout for workspace samples and artifact assertions. -4. Keep Studio integration contract-based so Studio does not depend on filesystem internals. - -## Acceptance Criteria - -- `prometeu-packer` exists as a separate build target -- packer contracts compile without depending on Studio UI classes -- future PRs can add implementations without restructuring the project root -- packer test infrastructure is usable from the next PR onward - -## Validation - -- build graph includes `prometeu-packer` -- baseline compile test for public contracts -- fixture-loading smoke test in the new project - -## Affected Artifacts - -- `settings.gradle.kts` -- `prometeu-packer/**` -- repository build wiring -- cross-domain reference: Studio adapter call sites that will later consume packer services diff --git a/docs/packer/pull-requests/PR-02-workspace-init-registry-and-identity-foundation.md b/docs/packer/pull-requests/PR-02-workspace-init-registry-and-identity-foundation.md deleted file mode 100644 index a2fa88fc..00000000 --- a/docs/packer/pull-requests/PR-02-workspace-init-registry-and-identity-foundation.md +++ /dev/null @@ -1,60 +0,0 @@ -# PR-02 Workspace Init, Registry, and Identity Foundation - -Domain Owner: `docs/packer` - -## Briefing - -Implement the packer-owned workspace control model and registry authority in `prometeu-packer`. - -This PR turns the identity and workspace rules into executable code. - -## Objective - -Deliver `init_workspace`, registry load/store, identity allocation, and asset-root resolution as the stable foundation for all later packer operations. - -## Dependencies - -- [`./PR-01-packer-project-bootstrap-and-module-boundaries.md`](./PR-01-packer-project-bootstrap-and-module-boundaries.md) -- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md) -- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) - -## Scope - -- implement `init_workspace` -- create and validate `assets/.prometeu/index.json` -- implement monotonic `asset_id` allocation and persisted allocator state -- model `asset_uuid` allocation and persistence -- implement root resolution utilities used by future read/write operations -- define structural registry errors and missing-root behavior - -## Non-Goals - -- no `asset.json` semantic validation beyond what registry ownership requires -- no Studio adapter yet -- no build artifacts yet - -## Execution Method - -1. Implement packer-owned registry models and codecs. -2. Add workspace bootstrap behavior for missing control directories. -3. Enforce identity invariants around `asset_id`, `asset_uuid`, and root uniqueness. -4. Expose internal services for lookup by `asset_id`, `asset_uuid`, and root path. - -## Acceptance Criteria - -- workspace initialization creates the minimum control structure deterministically -- registry state round-trips without losing allocator data -- duplicate or ambiguous identity-bearing entries fail clearly -- relocation can later update root location without changing identity fields - -## Validation - -- unit tests for registry round-trip and allocator monotonicity -- unit tests for duplicate-root and malformed-registry failures -- workspace-init fixture test - -## Affected Artifacts - -- `prometeu-packer/**` -- `assets/.prometeu/index.json` contract implementation -- packer fixture workspaces diff --git a/docs/packer/pull-requests/PR-03-asset-declaration-parsing-validation-and-details-contract.md b/docs/packer/pull-requests/PR-03-asset-declaration-parsing-validation-and-details-contract.md deleted file mode 100644 index c48ca4d7..00000000 --- a/docs/packer/pull-requests/PR-03-asset-declaration-parsing-validation-and-details-contract.md +++ /dev/null @@ -1,65 +0,0 @@ -# PR-03 Asset Declaration Parsing, Validation, and Details Contract - -Domain Owner: `docs/packer` - -## Briefing - -Implement strict `asset.json` parsing and the packer-side details contract used by both tooling and Studio. - -This PR converts the declaration spec into typed packer models and structured diagnostics. - -## Objective - -Deliver strict parse, schema/version checks, common field validation, and a `get_asset_details` response model that Studio can consume through an adapter. - -## Dependencies - -- [`./PR-02-workspace-init-registry-and-identity-foundation.md`](./PR-02-workspace-init-registry-and-identity-foundation.md) -- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md) - -## Scope - -- parse and validate the common `asset.json` contract -- validate required baseline fields: - - `schema_version` - - `name` - - `type` - - `inputs` - - `output` - - `preload` -- emit structured diagnostics for parse, structural, and version errors -- define the packer `get_asset_details` response model -- preserve distinction between valid-orphan declarations and invalid declarations - -## Non-Goals - -- no full format-family payload encoding rules -- no workspace scan aggregation yet -- no mutation apply behavior yet - -## Execution Method - -1. Implement typed declaration models and strict decoding. -2. Add common semantic validation and diagnostic mapping. -3. Define details-response DTOs that preserve both declaration and diagnostic evidence. -4. Back the contract with representative valid and invalid fixtures. - -## Acceptance Criteria - -- invalid declarations fail with actionable structured diagnostics -- valid declarations produce stable typed models -- `get_asset_details` can expose declaration, inputs, output, preload, and diagnostics cleanly -- unsupported or malformed schema versions surface as explicit failures - -## Validation - -- fixture-driven parser tests -- semantic validation tests for required fields -- details-response tests for valid, orphan, and invalid declarations - -## Affected Artifacts - -- `prometeu-packer/**` -- packer declaration fixtures -- cross-domain reference: Studio asset details adapter inputs diff --git a/docs/packer/pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md b/docs/packer/pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md deleted file mode 100644 index ec849a9b..00000000 --- a/docs/packer/pull-requests/PR-04-workspace-scan-list-assets-and-studio-read-adapter.md +++ /dev/null @@ -1,61 +0,0 @@ -# PR-04 Workspace Scan, List Assets, and Studio Read Adapter - -Domain Owner: `docs/packer` - -## Briefing - -Implement the read-side operational surface that turns a filesystem workspace into a packer-owned asset snapshot. - -This PR is the first explicit Studio integration step: Studio stops reading the workspace directly and starts consuming a packer response model through an adapter. - -## Objective - -Deliver `list_assets`, wire `get_asset_details` over real workspace scanning, and create the read adapter that maps packer responses to Studio workspace models. - -## Dependencies - -- [`./PR-03-asset-declaration-parsing-validation-and-details-contract.md`](./PR-03-asset-declaration-parsing-validation-and-details-contract.md) -- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) - -## Scope - -- implement workspace scanning for managed assets and orphan anchors -- implement `list_assets` -- finish real `get_asset_details` on top of packer services -- distinguish managed-world structural issues from workspace hygiene findings in read responses -- create the Studio read adapter from packer responses to the existing Studio asset workspace models -- replace filesystem-specific read code in Studio with the adapter-backed path - -## Non-Goals - -- no sensitive mutation apply flows yet -- no build pipeline yet -- no event lane yet - -## Execution Method - -1. Scan `assets/` for anchored roots and reconcile against the registry. -2. Produce a structured snapshot for list/details services. -3. Implement a Studio adapter that maps packer DTOs into the Studio read model without embedding packer logic in JavaFX. -4. Verify that Studio read behavior remains equivalent while packer becomes the source of truth. - -## Acceptance Criteria - -- `list_assets` returns managed and orphan assets coherently -- Studio navigator and details surfaces can run on packer-backed read responses -- registry authority remains visible in the mapped Studio state -- invalid declarations and missing roots surface through structured diagnostics - -## Validation - -- packer tests for scan reconciliation and orphan detection -- adapter tests for mapping list/details responses into Studio models -- Studio smoke validation using the packer-backed read path - -## Affected Artifacts - -- `prometeu-packer/**` -- `prometeu-studio/**` read adapters and service wiring -- test fixtures shared across packer and Studio integration tests diff --git a/docs/packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md b/docs/packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md deleted file mode 100644 index 8a0d4f30..00000000 --- a/docs/packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md +++ /dev/null @@ -1,78 +0,0 @@ -# PR-05 Sensitive Mutations, Preview/Apply, and Studio Write Adapter - -Domain Owner: `docs/packer` - -## Briefing - -Implement the packer-owned preview/apply mutation services and route Studio staged mutations through a write adapter instead of local filesystem rules. - -This PR is where the current Studio staged mutation UI starts executing real packer semantics. - -## Objective - -Deliver structured preview/apply services for `register_asset`, `adopt_asset`, `forget_asset`, `remove_asset`, quarantine, and relocation, plus the Studio adapter that maps packer mutation responses into the existing staged mutation UI. - -## Dependencies - -- [`./PR-04-workspace-scan-list-assets-and-studio-read-adapter.md`](./PR-04-workspace-scan-list-assets-and-studio-read-adapter.md) -- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- cross-domain reference: [`../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md`](../../studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md) - -## Scope - -- implement preview/apply service contracts for: - - `register_asset` - - `adopt_asset` - - `forget_asset` - - `remove_asset` - - `quarantine_asset` - - `relocate_asset` -- preserve explicit distinction between: - - registry mutations - - workspace mutations - - blockers - - warnings - - safe fixes -- implement mutation serialization rules so conflicting write flows do not race -- implement the baseline single-writer semantic lane per project for sensitive mutation apply -- create the Studio write adapter for staged mutation preview/apply -- replace filesystem-only Studio mutation execution with packer-backed services - -## Non-Goals - -- no doctor implementation yet -- no build artifact emission yet -- no generic cross-workspace mutation framework - -## Execution Method - -1. Implement staged intent models and preview/apply response types in the packer. -2. Implement mutation handlers on top of registry and workspace services. -3. Serialize final mutation apply within a project-scoped write lane while keeping preview generation outside the commit-critical section when safe. -4. Add a Studio adapter that converts packer mutation responses into the current staged preview model and forwards packer-native lifecycle events into the Studio event bus. -5. Retire duplicated mutation semantics from Studio once the adapter path is stable. - -## Acceptance Criteria - -- sensitive mutations run through packer preview/apply services -- Studio staged mutation UI no longer owns core mutation semantics -- relocation preserves `asset_id` and `asset_uuid` -- quarantine is explicit, previewable, and reversible in service semantics -- mutation failures remain actionable and structured -- conflicting mutation applies on the same project cannot commit concurrently -- mutation lifecycle can be surfaced to Studio without Studio inventing semantic outcomes - -## Validation - -- packer tests for each sensitive mutation preview/apply path -- packer concurrency tests for same-project conflicting writes -- adapter tests for mapping packer responses into Studio preview models -- adapter tests for forwarding packer mutation lifecycle events into Studio events -- Studio smoke validation for preview/apply against the packer-backed path - -## Affected Artifacts - -- `prometeu-packer/**` -- `prometeu-studio/**` mutation adapter and wiring -- mutation fixture workspaces diff --git a/docs/packer/pull-requests/PR-06-doctor-diagnostics-and-safe-fix-baseline.md b/docs/packer/pull-requests/PR-06-doctor-diagnostics-and-safe-fix-baseline.md deleted file mode 100644 index 6271ec7a..00000000 --- a/docs/packer/pull-requests/PR-06-doctor-diagnostics-and-safe-fix-baseline.md +++ /dev/null @@ -1,60 +0,0 @@ -# PR-06 Doctor, Diagnostics, and Safe-Fix Baseline - -Domain Owner: `docs/packer` - -## Briefing - -Implement the baseline doctor and diagnostics model for the production packer. - -This PR is responsible for making the packer operationally useful beyond navigation and mutation flows. - -## Objective - -Deliver structured doctor execution with managed-world validation, expanded workspace hygiene scanning, and safe-fix preview/apply where baseline-safe. - -## Dependencies - -- [`./PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](./PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md) - -## Scope - -- implement managed-world structural validation -- implement expanded workspace hygiene scanning -- classify diagnostics by severity and blocking behavior -- implement safe mechanical fix flows for baseline-safe cases only -- expose doctor responses in structured form for Studio and CI consumption -- define evidence and summaries suitable for Activity and inline diagnostics - -## Non-Goals - -- no silent destructive repair -- no speculative auto-healing of relocational or delete scenarios -- no final watch mode yet - -## Execution Method - -1. Implement diagnostic producers for registry, declaration, and workspace hygiene findings. -2. Implement doctor request modes and safe-fix eligibility checks. -3. Model doctor output as structured responses instead of terminal-only text. -4. Connect safe-fix preview/apply behavior to the same safety rules used by mutation flows. - -## Acceptance Criteria - -- blocking and non-blocking diagnostics are clearly separated -- doctor can report on both managed-world validity and broader hygiene issues -- safe fixes only exist where the operation is explicitly low-risk -- Studio and CI can consume the same doctor response model - -## Validation - -- fixture tests for structural errors and hygiene findings -- tests for safe-fix eligibility and refusal paths -- adapter tests for Studio diagnostic mapping - -## Affected Artifacts - -- `prometeu-packer/**` -- cross-domain reference: Studio diagnostics and activity consumers -- doctor fixtures and expected reports diff --git a/docs/packer/pull-requests/PR-07-build-plan-determinism-and-cache-key-foundation.md b/docs/packer/pull-requests/PR-07-build-plan-determinism-and-cache-key-foundation.md deleted file mode 100644 index 5da2383e..00000000 --- a/docs/packer/pull-requests/PR-07-build-plan-determinism-and-cache-key-foundation.md +++ /dev/null @@ -1,62 +0,0 @@ -# PR-07 Build Plan, Determinism, and Cache-Key Foundation - -Domain Owner: `docs/packer` - -## Briefing - -Implement the deterministic planning layer that normalizes validated assets into a stable build plan before artifact emission. - -This PR is the boundary between workspace semantics and runtime-facing artifact production. - -## Objective - -Deliver a deterministic build planner, canonical header model, preload derivation, and cache-key foundation that later emission and incremental work can trust. - -## Dependencies - -- [`./PR-06-doctor-diagnostics-and-safe-fix-baseline.md`](./PR-06-doctor-diagnostics-and-safe-fix-baseline.md) -- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -## Scope - -- validate build-eligible managed assets -- derive deterministic asset ordering by increasing `asset_id` -- build canonical header-side models for: - - `asset_table` - - `preload` -- define payload planning slots and offset planning inputs -- compute cache keys from validated effective inputs -- emit deterministic in-memory build plans before writing files - -## Non-Goals - -- no final `assets.pa` file emission yet -- no watch mode yet -- no format-family semantic expansion beyond what current specs already define - -## Execution Method - -1. Normalize validated managed assets into a stable build plan representation. -2. Implement canonical JSON serialization rules for header mirrors and planner assertions. -3. Compute cache keys only from validated effective inputs. -4. Add deterministic tests proving equivalent workspaces produce equivalent plans. - -## Acceptance Criteria - -- equivalent inputs produce equivalent build plans -- asset ordering is independent from filesystem traversal order -- preload derivation matches declaration state deterministically -- cache-key inputs are explicit and reproducible - -## Validation - -- determinism tests with reordered filesystem fixtures -- canonical-header serialization tests -- cache-key stability tests - -## Affected Artifacts - -- `prometeu-packer/**` -- build planning fixtures -- future dependency for `build` service and event lane diff --git a/docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md b/docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md deleted file mode 100644 index 6e1702ca..00000000 --- a/docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md +++ /dev/null @@ -1,63 +0,0 @@ -# PR-08 assets.pa and Companion Artifact Emission - -Domain Owner: `docs/packer` - -## Briefing - -Implement writer-side artifact emission on top of the deterministic build planner. - -This PR turns validated and planned build state into the published packer outputs. - -## Objective - -Deliver `build`, `assets.pa`, and the baseline companion artifacts with deterministic ordering and stable writer-side contracts. - -## Dependencies - -- [`./PR-07-build-plan-determinism-and-cache-key-foundation.md`](./PR-07-build-plan-determinism-and-cache-key-foundation.md) -- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md) -- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) - -## Scope - -- implement the `build` service -- emit `assets.pa` -- emit: - - `build/asset_table.json` - - `build/preload.json` - - `build/asset_table_metadata.json` -- implement canonical header serialization and file writing -- implement payload-region offset materialization from the build plan -- expose build summaries and applied-artifact metadata for Studio and CI - -## Non-Goals - -- no cartridge assembly -- no shipper coupling -- no speculative layout optimization beyond deterministic packing - -## Execution Method - -1. Convert the build plan into emitted artifact bytes and companion files. -2. Preserve header authority and 1:1 mirror rules for companion JSON outputs. -3. Add golden fixtures for emitted headers and companion artifacts. -4. Keep runtime-facing semantics bounded to writer-side production rules already specified. - -## Acceptance Criteria - -- `build` produces `assets.pa` and companion artifacts deterministically -- companion JSON outputs mirror the runtime header where required -- emitted ordering and offsets follow the build plan contract -- repeated equivalent builds do not drift - -## Validation - -- golden tests for `assets.pa` envelope and header bytes -- golden tests for companion JSON mirrors -- repeated-build determinism tests - -## Affected Artifacts - -- `prometeu-packer/**` -- build output fixtures -- CI artifact assertions diff --git a/docs/packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md b/docs/packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md deleted file mode 100644 index fb2ca9b8..00000000 --- a/docs/packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md +++ /dev/null @@ -1,83 +0,0 @@ -# PR-09 Event Lane, Progress, and Studio Operational Integration - -Domain Owner: `docs/packer` - -## Briefing - -Implement the packer event/reporting lane and bind the production packer service lifecycle into Studio operational surfaces. - -This PR is where Studio stops inferring operational history locally and starts reflecting packer-native lifecycle events. - -## Objective - -Deliver the structured packer event lane, progress reporting, and adapter/wiring so Studio Activity, progress, and refresh behavior align with real packer execution. - -## Dependencies - -- [`./PR-08-assets-pa-and-companion-artifact-emission.md`](./PR-08-assets-pa-and-companion-artifact-emission.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- cross-domain reference: [`../../studio/specs/1. Studio Shell and Workspace Layout Specification.md`](../../studio/specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) -- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) - -## Scope - -- implement the initial structured event set: - - `asset_discovered` - - `asset_changed` - - `diagnostics_updated` - - `build_started` - - `build_finished` - - `cache_hit` - - `cache_miss` - - `preview_ready` - - `action_applied` - - `action_failed` - - `progress_updated` -- define the baseline event envelope with fields equivalent to: - - `project_id` - - `operation_id` - - `sequence` - - `kind` - - `timestamp` - - `summary` - - `progress` - - `affected_assets` -- define event publishing hooks across scan, doctor, mutation, and build flows -- implement the Studio adapter from packer events to Studio event bus semantics -- align global Activity and progress behavior with packer-native lifecycle updates - -## Non-Goals - -- no final watch daemon -- no remote/shared cache orchestration -- no UI redesign - -## Execution Method - -1. Add event publication points to read, mutation, doctor, and build services. -2. Define a packer event sink abstraction so Studio is a consumer, not the owner, of the event model. -3. Preserve operation causality with stable `operation_id` plus monotonic per-operation `sequence`. -4. Map packer events into existing Studio Activity and progress surfaces through an adapter, with coalescing only for low-value repeated progress-like events. -5. Verify that long-running work does not block UI interaction and that terminal lifecycle events remain individually visible. - -## Acceptance Criteria - -- packer emits structured lifecycle events across core operations -- Studio Activity/progress can be driven from packer-native events -- mutation and build flows no longer require Studio-local event invention -- event ordering is coherent from the UI perspective -- same-operation event ordering is preserved through the Studio adapter -- adapters may remap event shapes, but do not invent causal relationships or semantic summaries absent from the packer event stream - -## Validation - -- packer event publication tests -- adapter tests from packer events to Studio events -- ordering/coalescing tests for progress-heavy operations and terminal lifecycle events -- Studio smoke validation for Activity and progress during packer-backed operations - -## Affected Artifacts - -- `prometeu-packer/**` -- `prometeu-studio/**` event adapter and wiring -- integration fixtures for long-running operations diff --git a/docs/packer/pull-requests/PR-10-versioning-migration-trust-and-production-gates.md b/docs/packer/pull-requests/PR-10-versioning-migration-trust-and-production-gates.md deleted file mode 100644 index 6dd89c01..00000000 --- a/docs/packer/pull-requests/PR-10-versioning-migration-trust-and-production-gates.md +++ /dev/null @@ -1,70 +0,0 @@ -# PR-10 Versioning, Migration, Trust, and Production Gates - -Domain Owner: `docs/packer` - -## Briefing - -Finish the production track by hardening the packer against version skew, corrupted inputs, and unsupported artifacts, while installing CI and integration gates for the standalone project. - -This PR closes the packer implementation wave with production readiness checks rather than new feature surface. - -## Objective - -Deliver explicit version checks, migration ownership behavior, trust-boundary enforcement, and production test gates for `prometeu-packer` and its Studio integration path. - -## Dependencies - -- [`./PR-09-event-lane-progress-and-studio-operational-integration.md`](./PR-09-event-lane-progress-and-studio-operational-integration.md) -- [`../specs/6. Versioning, Migration, and Trust Model Specification.md`](../specs/6.%20Versioning,%20Migration,%20and%20Trust%20Model%20Specification.md) -- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) - -## Scope - -- implement explicit version checking across: - - `asset.json` - - `index.json` - - packer-owned cache/control schemas - - `assets.pa` writer-side contract surfaces -- implement supported-window failure behavior and migration reporting -- enforce conservative trust checks before parse, validation, mutation, and build -- add CI gates and end-to-end fixtures for: - - read flows - - mutation preview/apply flows - - doctor - - build - - Studio adapter integration -- consolidate operational docs and production readiness notes for the packer project - -## Non-Goals - -- no plugin system -- no artifact signing strategy -- no remote registry or shared-cache product surface - -## Execution Method - -1. Add version and migration checks to all packer-owned artifact boundaries. -2. Make unsupported-version and migration failures explicit and structured. -3. Add end-to-end integration fixtures that exercise the standalone packer with the Studio adapter path. -4. Install repository gates so production regressions fail before merge. - -## Acceptance Criteria - -- unsupported versions fail early and clearly -- migration attempts and failures are visible to Studio and CI -- packer trust boundaries are enforced before unsafe work proceeds -- `prometeu-packer` has end-to-end production gates covering its declared service surface - -## Validation - -- version-compatibility and migration tests -- malformed/untrusted input hardening tests -- end-to-end integration tests across packer plus Studio adapter path -- CI execution proving the packer project is gated independently - -## Affected Artifacts - -- `prometeu-packer/**` -- repository CI/build configuration -- `prometeu-studio/**` integration gates where the adapter path is exercised -- packer learn/spec propagation targets after implementation diff --git a/docs/packer/pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md b/docs/packer/pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md deleted file mode 100644 index 6ca14efc..00000000 --- a/docs/packer/pull-requests/PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md +++ /dev/null @@ -1,194 +0,0 @@ -# PR-11 Packer Runtime Restructure, Snapshot Authority, and Durable Commit - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The current `prometeu-packer` production track established the packer as the semantic owner of asset state, write semantics, diagnostics, and operational events. - -The next architectural step is to restructure the packer so it behaves like a filesystem-first project-scoped operational runtime for the service surface the Studio actually uses today, rather than a collection of filesystem-per-call services: - -- reads should come from a coherent in-memory snapshot; -- writes should execute through a packer-owned write path; -- state transitions should be coordinated by the packer, not by incidental caller sequencing; -- durable visibility should be defined by commit to disk, not by partially observed intermediate filesystem state; -- Studio should remain a frontend consumer of packer-owned read/write/event contracts. - -This is a service-first re-architecture program, not a cosmetic refactor. -The likely outcome is a substantial internal rewrite of the packer service layer while preserving and tightening the external semantic contract already defined by the packer specs. - -The current wave is intentionally narrow: - -- build only the embedded service runtime needed by Studio asset management; -- remove unused or out-of-scope capabilities from the active code path instead of carrying them forward speculatively; -- reintroduce `doctor`, `build/pack`, and background reconcile only when a later concrete service need justifies them. - -This PR is an umbrella planning artifact only. -It does not authorize direct implementation work by itself. - -## Objective - -Define and execute a family of packer PRs that turns the packer into a project-scoped runtime with: - -- explicit read and write APIs; -- a coherent in-memory project snapshot; -- packer-owned threading for state write coordination; -- durable commit to workspace files as the persistence boundary; -- causality-preserving events for Studio and other tooling consumers; -- an aggressively reduced active surface focused on the service capabilities currently consumed by Studio. - -Communication model baseline: - -- request/response is the primary contract for queries and commands; -- events are the primary contract for asynchronous lifecycle, progress, divergence, and terminal operation reporting; -- synchronous command entrypoints may return a `Future` directly when the caller needs an operation handle for later completion; -- long-running command completion may still be observed through causality-preserving events correlated to that operation; -- the packer should not use events as a replacement for normal query/command response semantics. - -## Dependencies - -- [`../specs/1. Domain and Artifact Boundary Specification.md`](../specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md) -- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- [`../decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md`](../decisions/Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md) -- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) - -Decision baseline already in place: - -- [`../decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](../decisions/Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md) - -This PR is the umbrella execution plan for that direction. -It is not a substitute for that decision record and it is not itself an implementation PR. - -## Scope - -- lock the architectural target and implementation decomposition for the runtime-restructure wave -- perform cleanup and active-surface reduction before runtime work begins -- define a packer-internal project runtime model that owns one coherent state snapshot per active project -- define packer-owned read APIs that serve data from the runtime snapshot instead of recomputing the full model from disk for each call -- define a packer-owned write lane that executes on packer-controlled threading rather than caller-controlled sequencing -- define the durable commit model from in-memory state to workspace files under `assets/` and `assets/.prometeu/` -- define snapshot refresh/bootstrap/recovery behavior -- define embedded-host bootstrap rules for supplying the explicit `PackerEventSink` used by packer event publication, with host-side bridging to any shared typed event bus -- define the query/command versus event boundary for Studio integration -- define how synchronous command entrypoints expose `Future`-based completion to callers that need direct operation handles -- migrate only the service surface currently used by Studio asset management onto the runtime model -- remove or retire implementation paths that are not used by that active service wave -- preserve Studio as a consumer of packer responses and events, not an owner of packer semantics -- retire the current filesystem-per-call service style once the runtime-backed path is stable - -## Non-Goals - -- no direct code implementation inside `PR-11` -- no direct rollout of one monolithic runtime rewrite under one follow-up change -- no redesign of Studio workspace UX -- no remote daemon or IPC transport in this wave -- no distributed or multi-process transactional protocol -- no final watch-service design for external filesystem edits -- no `doctor` implementation in this wave -- no `build/pack` implementation in this wave -- no background reconcile implementation in this wave -- no silent semantic changes to asset identity, registry authority, or write behavior already defined in packer specs -- no replacement of the packer event model with Studio-local orchestration - -## Execution Method - -This work must be executed as a family of follow-up PRs. -`PR-11` freezes the target architecture and the decomposition logic, but implementation starts only in later PR documents. - -The follow-up implementation PR family is: - -1. [`PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md) -2. [`PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md`](./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md) -3. [`PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md) -4. [`PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -5. [`PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md) -6. [`PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md) -7. [`PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md) - -Each follow-up PR should remain granular enough to: - -- have a narrow acceptance surface; -- carry its own tests and rollback story; -- avoid mixing cleanup, bootstrap, runtime-core, UI-adapter, and deferred capability concerns in one code change. - -Wave discipline for all follow-up PRs: - -- remove code that is not used by the active Studio-facing service wave instead of preserving speculative extension points; -- do not reintroduce `doctor`, `build/pack`, or background reconcile as placeholders; -- add capabilities later only when the active Studio integration requires them. - -Deferred from the current wave: - -- `doctor` -- `build/pack` -- background reconcile/diff observer - -Those capabilities should be reintroduced only when the active service wave needs them. - -## Acceptance Criteria - -- `PR-11` remains an umbrella plan rather than a direct implementation vehicle -- the follow-up implementation family is clear enough that later PRs can be opened without reopening the architecture debate -- the packer has an explicit project-scoped runtime authority model -- read operations observe coherent snapshot state -- write operations are executed through packer-owned coordination on packer-controlled threading -- durable visibility is defined by successful commit, not by partially observed intermediate filesystem state -- same-project write conflicts cannot commit concurrently -- same-project read/write interaction does not expose torn committed truth -- asset identity, registry authority, and write semantics remain consistent with existing packer specs -- the active implementation surface contains only the service capabilities currently used by Studio -- unused or out-of-scope legacy capability paths are removed instead of lingering in parallel -- Studio consumes packer read/write/event APIs as a frontend consumer and does not regain semantic ownership -- request/response remains the primary query/command contract while events remain the asynchronous observability contract -- synchronous command APIs may expose `Future` completion directly without collapsing the event lane into ad hoc RPC polling -- event ordering and `operation_id` causality remain valid through the restructured runtime -- the packer keeps `PackerEventSink` as its publication boundary instead of depending directly on host event bus types -- embedded hosts may bridge `PackerEventSink` into a container-owned typed event bus, but the packer API must not normalize a silent `noop` default as production bootstrap behavior - -## Validation - -- snapshot bootstrap tests for projects with valid, invalid, and partially broken asset workspaces -- read coherence tests under concurrent read pressure -- write serialization tests for same-project conflicting writes -- failure and recovery tests for interrupted durable commit paths -- write-path regression tests on top of the runtime core for the commands currently used by Studio -- cleanup validation proving that inactive `doctor`, `build/pack`, and background reconcile implementation paths are no longer part of the active wave -- event ordering and terminal lifecycle tests through the Studio adapter path -- Studio smoke validation for: - - asset listing - - details loading - - staged writes - - relocation - - refresh after packer-owned operations -- bootstrap validation that Studio initializes the container-owned typed event bus before packer-backed runtime use - -## Risks and Rollback - -- this program may expose that the current service boundaries are too filesystem-centric to preserve cleanly -- removing out-of-scope capabilities now may require later reintroduction work when those capabilities become necessary again -- external filesystem edits during runtime lifetime are not fully solved by this plan and must not be hidden as if they were -- if runtime-backed services prove too invasive, rollback should preserve the current stable service contracts while isolating the runtime work behind new internal packages until the migration is complete - -## Affected Artifacts - -- `docs/packer/decisions/**` -- `docs/packer/pull-requests/**` -- `docs/packer/decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md` -- `docs/packer/specs/1. Domain and Artifact Boundary Specification.md` -- `docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md` -- `docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md` -- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md` -- `docs/packer/specs/6. Versioning, Migration, and Trust Model Specification.md` -- `docs/studio/specs/2. Studio UI Foundations Specification.md` -- `docs/studio/specs/4. Assets Workspace Specification.md` -- `prometeu-packer/src/main/java/p/packer/**` -- `prometeu-packer/src/test/java/p/packer/**` -- `prometeu-studio/**` integration adapter and smoke coverage - -## Suggested Next Step - -Do not start code execution directly from this plan. - -The next correct step is to derive granular implementation PRs from `PR-11`, each scoped to one execution front of the runtime-restructure wave. diff --git a/docs/packer/pull-requests/PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md b/docs/packer/pull-requests/PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md deleted file mode 100644 index 518f03e2..00000000 --- a/docs/packer/pull-requests/PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md +++ /dev/null @@ -1,74 +0,0 @@ -# PR-12 Cleanup and Unused Surface Removal Before the Runtime Service Wave - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -Before introducing the runtime service wave, the current packer code should be reduced and cleaned so the next PRs are not built on top of contradictory seams. - -The current code still mixes: - -- implicit concrete instantiation inside services; -- filesystem-per-call orchestration; -- service boundaries that do not match the desired runtime model; -- inactive or out-of-scope capabilities that are not part of the immediate Studio-driven service wave. - -This PR creates the cleanup baseline. - -## Objective - -Remove unused/out-of-scope packer surfaces, align code with the current specs, and prepare a smaller active service boundary for the runtime implementation track. - -## Dependencies - -- [`./PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](./PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md) -- [`../decisions/Filesystem-First Operational Runtime and Reconcile Boundary Decision.md`](../decisions/Filesystem-First%20Operational%20Runtime%20and%20Reconcile%20Boundary%20Decision.md) -- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) -- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -## Scope - -- align `asset.json` handling with the current spec baseline, including `asset_uuid` -- remove inactive `doctor`, `build/pack`, and reconcile-oriented implementation paths from the active runtime-service wave -- remove concrete default instantiation patterns that hide composition ownership -- simplify the active service surface to what the current Studio integration actually needs -- remove code that is not being used for the immediate service-only wave -- correct service contract seams that currently mix read-oriented and mutation-oriented responsibilities in contradictory ways - -## Non-Goals - -- no runtime snapshot yet -- no write lane yet -- no Studio adapter redesign yet -- no reintroduction of doctor/build/reconcile in this wave - -## Execution Method - -1. Align manifest/declaration code with the current spec baseline. -2. Remove inactive service paths that are not part of the current Studio-driven runtime wave. -3. Eliminate implicit composition where services instantiate concrete collaborators by default. -4. Correct active service contracts so the remaining surface matches the Studio-facing runtime plan. -5. Leave the repository with one smaller active surface that the runtime work can replace cleanly. - -## Acceptance Criteria - -- `asset_uuid` is no longer missing from the active declaration path -- inactive `doctor`, `build/pack`, and reconcile implementation paths are removed from the active wave -- concrete service composition is no longer hidden behind broad default constructors in the active path -- contradictory active service contracts are corrected before runtime work starts -- the remaining active surface is focused on the service capabilities the Studio currently needs - -## Validation - -- declaration/parser tests for the manifest baseline -- cleanup tests confirming out-of-scope service paths are no longer part of the active surface -- regression tests confirming the remaining active service surface still works -- smoke validation that Studio-facing packer usage still boots after the cleanup - -## Affected Artifacts - -- `prometeu-packer/src/main/java/p/packer/**` -- `prometeu-packer/src/test/java/p/packer/**` -- `prometeu-studio/**` only where the active service surface changes diff --git a/docs/packer/pull-requests/PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md b/docs/packer/pull-requests/PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md deleted file mode 100644 index 6fb5715c..00000000 --- a/docs/packer/pull-requests/PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md +++ /dev/null @@ -1,73 +0,0 @@ -# PR-13 Embedded Bootstrap, Container-Owned Event Bus, and Packer Composition Root - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -After the cleanup baseline, the next step is to make embedded Studio bootstrap explicit and introduce one composition root for the packer. - -This is where the Studio `Container` becomes a contract plus global holder, while the concrete embedded boot and `prometeu-packer-v1` wiring move into the application layer. - -## Objective - -Deliver the embedded bootstrap contract, explicit `PackerEventSink` wiring, and an explicit `prometeu-packer-api` to `prometeu-packer-v1` composition root for Studio embedding. - -## Dependencies - -- [`./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) -- cross-domain reference: [`../../studio/specs/2. Studio UI Foundations Specification.md`](../../studio/specs/2.%20Studio%20UI%20Foundations%20Specification.md) - -## Scope - -- define the embedded packer bootstrap contract -- define the packer composition root for the active service wave inside the application layer -- keep `prometeu-studio` bound only to `prometeu-packer-api` -- wire the Studio `Container` contract/holder as the owner of the shared typed event bus reference used by the host-side `PackerEventSink` bridge -- ensure application boot installs a `Container` implementation before packer-backed use begins -- make the active embedded runtime entrypoint explicit enough that future capabilities do not depend on hidden constructors or side boot paths - -## Non-Goals - -- no runtime snapshot yet -- no read migration yet -- no write lane yet -- no alternate bootstrap retained for inactive `doctor`, `build/pack`, or reconcile paths - -## Execution Method - -1. Define the explicit packer bootstrap/composition entrypoint. -2. Make the host-provided `PackerEventSink` an explicit dependency for Studio embedding. -3. Refactor Studio `Container` into a contract plus installed global holder. -4. Move concrete packer wiring to the application layer that chooses `prometeu-packer-v1`. -5. Remove remaining ambiguity around packer-local versus container-owned event visibility by bridging `PackerEventSink` into the host bus at the application layer. -5. Remove remaining embedded bootstrap variants that only exist to keep inactive service surfaces alive. - -## Acceptance Criteria - -- the active packer wave has one explicit composition root -- `prometeu-studio` depends only on `prometeu-packer-api` -- the application layer installs the `Container` implementation and chooses `prometeu-packer-v1` -- Studio `Container` owns the shared typed event bus reference through its installed implementation -- the packer composition root receives an explicit `PackerEventSink` rather than reaching directly into host event bus types -- packer-backed work starts only after `Container.install(...)` -- packer publication uses `PackerEventSink`, and the application layer bridges that sink into the container-owned path when embedded in Studio -- no public `PackerEventSink.noop()`-style default is treated as acceptable production bootstrap behavior -- hidden bootstrap paths that only support inactive service surfaces are removed - -## Validation - -- bootstrap tests for the packer composition root -- Studio boot tests for `Container.install(...)` -- integration tests for packer event visibility through the host bridge into the container-owned path - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**` -- `prometeu-studio/src/main/java/p/studio/Container.java` -- `prometeu-studio/src/main/java/p/studio/events/**` -- `prometeu-app/src/main/java/p/studio/App.java` -- `prometeu-app/src/main/java/p/studio/AppContainer.java` diff --git a/docs/packer/pull-requests/PR-14-project-runtime-core-snapshot-model-and-lifecycle.md b/docs/packer/pull-requests/PR-14-project-runtime-core-snapshot-model-and-lifecycle.md deleted file mode 100644 index b8708c9f..00000000 --- a/docs/packer/pull-requests/PR-14-project-runtime-core-snapshot-model-and-lifecycle.md +++ /dev/null @@ -1,68 +0,0 @@ -# PR-14 Project Runtime Core, Snapshot Model, and Lifecycle - -Domain Owner: `docs/packer` - -## Briefing - -With cleanup and bootstrap in place, the packer can now introduce the actual project runtime. - -This PR adds the runtime boundary, snapshot state model, bootstrap/load behavior, and disposal lifecycle that later query and command services will use. - -## Objective - -Deliver the project-scoped runtime core and one coherent in-memory snapshot model for the active service wave. - -## Dependencies - -- [`./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md) -- [`./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md`](./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md) -- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -## Scope - -- add the project runtime abstraction -- define snapshot content and generation ownership only for the active service wave -- define runtime bootstrap/load and disposal behavior -- isolate filesystem repositories behind the runtime boundary -- keep snapshot scope limited to the data needed by the active Studio-facing service path -- keep the runtime implementation inside `prometeu-packer-v1` while preserving the external contract in `prometeu-packer-api` - -## Non-Goals - -- no Studio adapter work yet -- no doctor/build/reconcile functionality -- no full query migration yet -- no write lane yet -- no speculative snapshot fields for capabilities that are not part of the active wave - -## Execution Method - -1. Introduce project runtime state/container types. -2. Load registry plus asset declarations into the runtime snapshot. -3. Define runtime generation, refresh, and disposal rules. -4. Keep the runtime state minimal and aligned with the currently used service surface. -5. Make later query/command work depend on this runtime boundary rather than direct filesystem scans. - -## Acceptance Criteria - -- one coherent runtime exists per active project -- runtime bootstrap/load is explicit and testable -- runtime disposal is explicit -- filesystem repositories are isolated behind the runtime boundary -- runtime state is limited to what the active Studio service wave actually consumes - -## Validation - -- runtime bootstrap tests -- snapshot generation tests -- lifecycle tests for bootstrap, refresh, and disposal - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**` diff --git a/docs/packer/pull-requests/PR-15-snapshot-backed-asset-query-services.md b/docs/packer/pull-requests/PR-15-snapshot-backed-asset-query-services.md deleted file mode 100644 index ac50113a..00000000 --- a/docs/packer/pull-requests/PR-15-snapshot-backed-asset-query-services.md +++ /dev/null @@ -1,70 +0,0 @@ -# PR-15 Snapshot-Backed Asset Query Services - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The first functional runtime-backed service wave should focus on queries. - -This PR moves the asset query surface used by Studio onto the runtime snapshot and defines coherent query behavior without expanding into doctor/build/reconcile. - -## Objective - -Deliver snapshot-backed query services for the currently used asset-management surface. - -## Dependencies - -- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md) -- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) -- [`../specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md) -- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) - -## Scope - -- migrate `init_workspace` -- migrate `list_assets` -- migrate `get_asset_details` -- keep the query path coherent through the runtime snapshot -- preserve the packer-owned summary/details contract used by Studio -- remove leftover query orchestration that only existed to feed inactive `doctor`, `build/pack`, or reconcile flows -- preserve the modular boundary where `prometeu-studio` consumes only `prometeu-packer-api` - -## Non-Goals - -- no command/write lane yet -- no mutation apply yet -- no doctor/build/reconcile - -## Execution Method - -1. Route the active query APIs through the runtime snapshot. -2. Preserve coherent results across repeated query use. -3. Remove repeated recomputation from the active query path. -4. Remove active query seams that only support deferred capabilities. -5. Keep Studio-facing response semantics stable. - -## Acceptance Criteria - -- active asset queries are served from the runtime snapshot -- normal query use no longer depends on full filesystem recomputation -- Studio-facing details/listing semantics remain stable -- no doctor/build/reconcile behavior is introduced by this PR -- unused query seams kept only for deferred capabilities are removed from the active path - -## Validation - -- regression tests for `init_workspace` -- regression tests for `list_assets` -- regression tests for `get_asset_details` -- Studio smoke validation for list/details loading - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**` -- `prometeu-studio/**` query adapter coverage diff --git a/docs/packer/pull-requests/PR-16-write-lane-command-completion-and-used-write-services.md b/docs/packer/pull-requests/PR-16-write-lane-command-completion-and-used-write-services.md deleted file mode 100644 index f882bc11..00000000 --- a/docs/packer/pull-requests/PR-16-write-lane-command-completion-and-used-write-services.md +++ /dev/null @@ -1,71 +0,0 @@ -# PR-16 Write Lane, Command Completion, and Used Write Services - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -After queries are runtime-backed, the next step is the minimal command surface actually used by Studio. - -This PR introduces the project write lane, synchronous command completion semantics, and the write services currently needed by Studio, without reintroducing doctor, build, or reconcile work. - -## Objective - -Deliver the write lane plus only the write/command surface currently exercised by the Studio `Assets` workspace on top of the runtime model. - -## Dependencies - -- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md) -- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -- [`../decisions/Concurrency, Observability, and Studio Adapter Boundary Decision.md`](../decisions/Concurrency,%20Observability,%20and%20Studio%20Adapter%20Boundary%20Decision.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -## Scope - -- implement the project-scoped write lane -- define durable visibility after successful commit -- define request/response command semantics with optional `Future`-based completion -- implement only the write surface currently used by Studio `Assets` -- preserve causal lifecycle events for command execution -- reintroduce command/write support in `prometeu-packer-v1` without collapsing the `prometeu-packer-api` boundary - -## Non-Goals - -- no doctor -- no build/pack -- no background reconcile observer - -## Execution Method - -1. Add the runtime-backed write lane. -2. Define synchronous command response plus optional `Future` completion semantics. -3. Reintroduce only the currently used write services onto the runtime. -4. Remove command surfaces that remain out of scope for the active Studio service wave. -5. Preserve asynchronous lifecycle events as observability, not as the primary command contract. - -## Acceptance Criteria - -- same-project commands are serialized by the packer -- committed state becomes visible only after successful durable commit -- synchronous command APIs may expose `Future` completion directly -- the write services currently used by Studio run on the runtime-backed path -- no doctor/build/reconcile behavior is introduced by this PR -- deferred command surfaces are not kept alive in the active implementation by placeholder adapters - -## Validation - -- write-lane concurrency tests -- commit failure/recovery tests -- command completion tests for response plus `Future` -- write regression tests for the active Studio write surface -- negative validation proving `doctor`, `build/pack`, and reconcile command paths are not part of the active wave - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**` -- `prometeu-studio/**` command integration coverage diff --git a/docs/packer/pull-requests/PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md b/docs/packer/pull-requests/PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md deleted file mode 100644 index e62fda59..00000000 --- a/docs/packer/pull-requests/PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md +++ /dev/null @@ -1,73 +0,0 @@ -# PR-17 Studio Runtime Adapter and Assets Workspace Consumption - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -Once the active query and command surface is runtime-backed, Studio should consume that path as a frontend without recreating packer semantics. - -This PR hardens the Studio adapters and the `Assets` workspace consumption path for the service-only wave while preserving the modular split between `prometeu-packer-api`, `prometeu-packer-v1`, `prometeu-studio`, and `prometeu-app`. - -## Objective - -Deliver the Studio-side adapter and `Assets` workspace integration for the active runtime-backed service surface. - -## Dependencies - -- [`./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md`](./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md) -- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md) -- cross-domain reference: [`../../studio/specs/2. Studio UI Foundations Specification.md`](../../studio/specs/2.%20Studio%20UI%20Foundations%20Specification.md) -- cross-domain reference: [`../../studio/specs/4. Assets Workspace Specification.md`](../../studio/specs/4.%20Assets%20Workspace%20Specification.md) - -## Scope - -- adapt Studio to consume runtime-backed packer queries and commands -- preserve `request/response` as the primary integration model -- consume packer lifecycle events through the host bridge from `PackerEventSink` into the container-owned typed event bus path -- keep the `Assets` workspace aligned with the active service-only wave -- remove adapter branches that only exist for inactive `doctor`, `build/pack`, or reconcile usage -- keep `prometeu-studio` bound only to `prometeu-packer-api` -- let `prometeu-app` remain responsible for installing the concrete `Container` implementation, applying the `p.packer.Packer` entrypoint from `prometeu-packer-v1`, and bridging `PackerEventSink` into the host bus - -## Non-Goals - -- no doctor UI -- no pack/build UI -- no reconcile-state UI beyond what the current service wave actually exposes - -## Execution Method - -1. Update the Studio adapter layer to consume the runtime-backed service path. -2. Preserve translational mapping only. -3. Validate that `prometeu-studio` does not depend on `prometeu-packer-v1` classes directly. -4. Validate command submission plus event-driven lifecycle visibility through the host `PackerEventSink` bridge and shared bus path. -4. Remove adapter branches that only keep deferred capabilities artificially wired. -5. Keep the `Assets` workspace focused on the currently active service surface. - -## Acceptance Criteria - -- Studio remains a consumer of packer runtime semantics -- `Assets` workspace list/details/actions run through the active runtime-backed service path -- command submission plus event observation are coherent end to end -- no inactive doctor/build/reconcile surfaces are reintroduced -- Studio adapters no longer preserve dead branches for deferred capability families -- `prometeu-studio` depends only on `prometeu-packer-api` -- `prometeu-app` is the layer that binds the concrete `Container` implementation and the `p.packer.Packer` entrypoint from `prometeu-packer-v1` -- Studio consumes packer lifecycle visibility through a host-provided `PackerEventSink` bridge rather than by exposing host bus types inside packer contracts - -## Validation - -- Studio adapter tests -- `Assets` workspace smoke tests -- end-to-end tests for list/details/write flows used by Studio - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/**` -- `prometeu-studio/src/test/java/p/studio/**` -- `prometeu-app/src/main/java/p/studio/**` -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` integration-facing contracts -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` embedded runtime implementation surfaces -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**` embedded runtime event surfaces diff --git a/docs/packer/pull-requests/PR-18-legacy-service-retirement-and-regression-hardening.md b/docs/packer/pull-requests/PR-18-legacy-service-retirement-and-regression-hardening.md deleted file mode 100644 index 15a324b3..00000000 --- a/docs/packer/pull-requests/PR-18-legacy-service-retirement-and-regression-hardening.md +++ /dev/null @@ -1,66 +0,0 @@ -# PR-18 Legacy Service Retirement and Regression Hardening - -Domain Owner: `docs/packer` - -## Briefing - -After the active service-only wave is fully running through the runtime path, the repository should not keep duplicated legacy orchestration around as a competing semantic track. - -This PR retires the superseded legacy paths and hardens regression coverage around the smaller active service surface. -It also closes the cleanup promise from `PR-12` by ensuring no unused packer capability families survive just because they existed before the runtime service wave. - -## Objective - -Remove superseded legacy service paths and strengthen regression protection for the runtime-backed service wave. - -## Dependencies - -- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md) -- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md) - -## Scope - -- retire duplicated filesystem-per-call paths superseded by the active runtime-backed service wave -- remove temporary shims that were tolerated only during the migration window -- harden regression coverage around the remaining active service surface -- remove leftover inactive `doctor`, `build/pack`, and reconcile code that no longer belongs to the service-only wave -- preserve the `prometeu-packer-api` surface as the stable consumer contract while retiring legacy implementation paths in `prometeu-packer-v1` - -## Non-Goals - -- no doctor reintroduction -- no build/pack reintroduction -- no reconcile observer work -- no new architecture decisions - -## Execution Method - -1. Remove superseded legacy paths. -2. Remove temporary migration shims once the runtime-backed path is complete. -3. Simplify the active service composition around the runtime boundary. -4. Strengthen regression coverage around the remaining service wave. -5. Verify no split-brain semantics remain between active and legacy paths. - -## Acceptance Criteria - -- superseded legacy paths are removed -- the active runtime-backed service wave is the only semantic path for the currently used functionality -- regression coverage protects the reduced active surface -- no inactive capability family survives in code solely as speculative future support - -## Validation - -- full active-service regression suite -- Studio embedding regression suite -- targeted tests proving no disagreement remains between active and legacy paths - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/events/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/**` -- integration fixtures diff --git a/docs/packer/pull-requests/PR-19-api-surface-audit-model-separation-and-public-read-dtos.md b/docs/packer/pull-requests/PR-19-api-surface-audit-model-separation-and-public-read-dtos.md deleted file mode 100644 index 6452c685..00000000 --- a/docs/packer/pull-requests/PR-19-api-surface-audit-model-separation-and-public-read-dtos.md +++ /dev/null @@ -1,98 +0,0 @@ -# PR-19 API Surface Audit, Model Separation, and Public Read DTOs - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The current packer API still exposes some read payload types that are simultaneously acting as public transport objects and internal implementation models. - -This is acceptable during early convergence, but it weakens the boundary between `prometeu-packer-api` and `prometeu-packer-v1`. - -The next cleanup step is to make the API explicit about three different categories: - -- domain contracts, -- request/response messages, -- public read DTOs. - -At the same time, the internal implementation models used by `prometeu-packer-v1` should stop leaking through the API as if they were stable public models. - -## Objective - -Separate internal `v1` read models from public API read DTOs while preserving: - -- request/response messages as immutable messages, -- domain contracts as domain contracts, -- exceptions as part of the public API, -- and Studio compatibility through explicit mapper-based conversion inside `prometeu-packer-v1`. - -## Dependencies - -- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md) -- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md) -- [`./PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md) - -## Scope - -- audit the current public packer API against real external consumption -- preserve public exceptions in the API even when only `v1` currently throws them -- preserve request/response records as request/response messages rather than renaming them as generic DTOs -- move the current mixed model/transport read types out of the API and into `prometeu-packer-v1` -- introduce public read DTOs in the API for the information Studio actually consumes -- add explicit mapper classes in `prometeu-packer-v1` to convert internal models into API DTOs -- keep the active service wave limited to `initWorkspace`, `listAssets`, `getAssetDetails`, and `createAsset` - -## Non-Goals - -- no new packer capabilities -- no write API redesign -- no doctor or build/pack reintroduction -- no reconcile observer work -- no semantic change to asset identity, registry ownership, or snapshot authority - -## Execution Method - -1. Classify the current API surface into: - - public domain contracts, - - public request/response messages, - - public read DTOs, - - internal implementation models. -2. Keep domain contracts in `prometeu-packer-api` without `DTO` suffixes. -3. Keep request/response types in `prometeu-packer-api` as immutable message records with `Request` and `Response` naming. -4. Move the current mixed read shapes now exposed as `PackerAssetSummary`, `PackerAssetDetails`, and `PackerAssetIdentity` into `prometeu-packer-v1` as internal models. -5. Introduce explicit public DTOs in the API for runtime-backed read payloads, such as: - - `PackerAssetSummaryDTO` - - `PackerAssetDetailsDTO` - - `PackerAssetIdentityDTO` - - `PackerCodecConfigurationFieldDTO` - - and `PackerDiagnosticDTO` if diagnostics remain part of public responses. -6. Add explicit mapper classes in `prometeu-packer-v1` to convert internal models into API DTOs before responses cross the module boundary. -7. Update response messages to carry the new DTO types instead of leaking `v1` models through the API. -8. Update Studio consumers to read from the new DTO types while preserving the same user-facing behavior. - -## Acceptance Criteria - -- the API surface is explicitly partitioned between domain contracts, request/response messages, and read DTOs -- request/response messages remain immutable message records and are not renamed as generic DTOs -- public exceptions remain in the API -- internal `v1` models are no longer exposed as if they were public API models -- Studio depends only on API contracts and DTOs, not on `v1` model semantics -- conversion from `v1` internal models to public API DTOs happens through explicit mapper code -- no behavior regression is introduced in `initWorkspace`, `listAssets`, `getAssetDetails`, or `createAsset` - -## Validation - -- compile-time audit proving `prometeu-studio` and `prometeu-app` consume only API contracts -- packer regression tests for read and write flows -- Studio regression tests for asset list, asset details, and add asset flows -- targeted tests for mapper coverage between internal models and public API DTOs - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**` -- `prometeu-studio/src/main/java/p/studio/**` -- `prometeu-studio/src/test/java/p/studio/**` - diff --git a/docs/packer/pull-requests/PR-20-asset-action-capabilities-and-register-first-delivery.md b/docs/packer/pull-requests/PR-20-asset-action-capabilities-and-register-first-delivery.md deleted file mode 100644 index e9807275..00000000 --- a/docs/packer/pull-requests/PR-20-asset-action-capabilities-and-register-first-delivery.md +++ /dev/null @@ -1,101 +0,0 @@ -# PR-20 Asset Action Capabilities and Register-First Delivery - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The current `Assets` workspace still decides too much locally about which asset actions should appear and when they should be allowed. - -That is the wrong long-term boundary. - -The packer already owns asset semantics, registration state, build participation, and write execution. It should also own the capability decision for asset actions, while Studio remains a consumer that renders the actions exposed by the service. - -This PR introduces a capability-based action contract driven by the packer, with `AssetAction.REGISTER` as the first delivered action end to end. - -## Objective - -Add a packer-owned asset action capability API and deliver the first action, `REGISTER`, through the full packer-to-Studio path. - -## Dependencies - -- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md) -- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md) -- [`./PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md) -- [`./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md`](./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md) - -## Scope - -- define a public packer action contract for asset capabilities -- let the packer decide which actions are available for a given asset at a given moment -- let Studio render the action section from packer-provided capabilities instead of local semantic rules -- keep the capability contract stable even if the packer later moves to FSM or another internal decision model -- deliver `AssetAction.REGISTER` as the first supported action end to end -- keep the service-only wave focused on active functionality - -## Non-Goals - -- no FSM implementation -- no full action family rollout in the first delivery -- no doctor/build/reconcile action surfaces -- no speculative future actions without packer support -- no frontend-local capability engine - -## Execution Method - -1. Add a public action capability contract in `prometeu-packer-api`, including: - - `AssetAction` enum - - capability response shape for asset actions - - request/response messages for reading action capabilities -2. Model the response so the packer can expose at least: - - `action` - - `enabled` - - `visible` - - optional `reason` -3. Add a runtime-backed read path in `prometeu-packer-v1` that resolves action capabilities from the current asset state. -4. Keep the internal decision logic inside the packer implementation. Studio must not reconstruct capability semantics. -5. Add a write path for `AssetAction.REGISTER`. -6. Expose `REGISTER` only when the asset capability resolver says it is allowed. -7. Render the `Actions` section in Studio from the returned capabilities. -8. Execute `REGISTER` from Studio through the packer write path and refresh the asset workspace after completion. - -## Register-First Delivery Rules - -The first delivered action is: - -- `AssetAction.REGISTER` - -Expected initial capability behavior: - -- unregistered assets may expose `REGISTER` -- registered assets must not expose `REGISTER` -- Studio must only show the `Register` button when the packer returns that capability - -Other future actions such as `MOVE`, `DELETE`, `INCLUDE_IN_BUILD`, `EXCLUDE_FROM_BUILD`, `ENABLE_PRELOAD`, `DISABLE_PRELOAD`, and `CHANGE_CONTRACT` are intentionally deferred from code delivery in this PR unless needed to support the contract shape. - -## Acceptance Criteria - -- the packer API exposes an asset action capability contract -- Studio reads action capabilities from the packer instead of deciding them locally -- the first delivered action is `AssetAction.REGISTER` -- `REGISTER` is available only for unregistered assets -- `REGISTER` is not shown for registered assets -- Studio can trigger `REGISTER` through the packer service path and refresh the workspace after success -- the capability contract remains valid if packer internals later migrate to FSM or another orchestration model - -## Validation - -- packer unit tests for capability resolution -- packer tests for `REGISTER` execution -- Studio tests or smoke tests proving that action buttons are rendered from service-provided capabilities -- end-to-end validation for unregistered asset -> register -> refresh -> registered asset - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**` -- `prometeu-studio/src/main/java/p/studio/**` -- `prometeu-studio/src/test/java/p/studio/**` - diff --git a/docs/packer/pull-requests/PR-21-point-in-memory-snapshot-updates-after-write-commit.md b/docs/packer/pull-requests/PR-21-point-in-memory-snapshot-updates-after-write-commit.md deleted file mode 100644 index 6005531e..00000000 --- a/docs/packer/pull-requests/PR-21-point-in-memory-snapshot-updates-after-write-commit.md +++ /dev/null @@ -1,77 +0,0 @@ -# PR-21 Point In-Memory Snapshot Updates After Write Commit - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The current write path still rebuilds the whole project runtime snapshot after a successful point write such as `REGISTER`. - -That is too expensive for the runtime model we want. - -Studio refresh on top of an already-updated in-memory snapshot is acceptable. Full filesystem rescan inside the packer after every point write is not. - -This PR replaces the normal post-write `full refresh` path with point snapshot updates in memory, while keeping full reload available only as an explicit recovery fallback. - -## Objective - -Remove whole-project runtime rescan from the normal point write path and replace it with point in-memory snapshot updates after durable commit. - -## Dependencies - -- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md) -- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md) -- [`./PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md) - -## Scope - -- add explicit point snapshot update support to the runtime registry -- keep the write lane as the only owner of point runtime mutation after durable commit -- replace post-write `runtimeRegistry.refresh(project)` in the active write path with point snapshot patching -- deliver the first point patch for `REGISTER` -- keep Studio refresh behavior unchanged - -## Non-Goals - -- no background divergence detection -- no reconcile loop -- no change to Studio refresh semantics -- no broad event model redesign -- no speculative patch implementation for unused write actions - -## Execution Method - -1. Extend the runtime registry so it can update a loaded project snapshot by applying a point patch function inside the packer-owned write flow. -2. Keep full snapshot reload available as recovery fallback, but do not use it in the normal successful point write path. -3. Model a point patch for `REGISTER` that: - - appends the new registry entry to the in-memory registry view - - updates the matching runtime asset from unregistered to registered - - preserves the rest of the snapshot untouched -4. Apply the patch only after the durable disk commit succeeds. -5. Keep read services unchanged from the Studio point of view; they should continue reading from the runtime snapshot. -6. Keep Studio free to refresh list/details after write completion, because those reads now hit the already-updated in-memory snapshot. -7. Add regression coverage proving that `REGISTER` no longer depends on whole-project rescan to become visible to subsequent reads. - -## Acceptance Criteria - -- successful point writes no longer trigger whole-project runtime rescan in the normal path -- the runtime registry supports point in-memory snapshot updates after durable commit -- `REGISTER` updates the loaded project snapshot in place -- subsequent `listAssets`, `getAssetDetails`, and `getAssetActions` read the updated state from memory -- Studio refresh after `REGISTER` remains valid and does not require frontend-local state patching -- full reload remains available only as fallback or explicit recovery path - -## Validation - -- packer tests for point snapshot patching on `REGISTER` -- packer tests proving read-after-write coherence without full runtime rebuild -- regression tests for fallback safety when point patching cannot be applied -- Studio smoke validation confirming existing refresh behavior still works on top of the updated runtime snapshot - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**` -- `prometeu-studio/src/main/java/p/studio/**` diff --git a/docs/packer/pull-requests/PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md b/docs/packer/pull-requests/PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md deleted file mode 100644 index 72ae1ea1..00000000 --- a/docs/packer/pull-requests/PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md +++ /dev/null @@ -1,77 +0,0 @@ -# PR-22 Delete Asset Action Confirmation and Fs-First Manifest Removal - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The action capability contract introduced in `PR-20` needs its next real delivery beyond `REGISTER`. - -`DELETE` must remove the asset from packer control without deleting the asset directory or its remaining files. The operation is filesystem-first: delete `asset.json`, update `index.json` when needed, and then apply a point snapshot update in memory. - -Studio must require explicit confirmation before calling this write path. - -## Objective - -Deliver `AssetAction.DELETE` end to end with packer-owned capability resolution, Studio confirmation modal, filesystem-first manifest removal, and point runtime snapshot update. - -## Dependencies - -- [`./PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md) -- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md) - -## Scope - -- extend the public action contract with `DELETE` -- expose `DELETE` capability from the packer for assets that currently own `asset.json` -- add a packer write path that deletes only `asset.json` -- remove any registered entry from `index.json` -- keep the asset directory and its non-manifest files on disk -- patch the loaded runtime snapshot in memory after successful delete -- add a Studio modal that requires typing the asset name before confirming deletion - -## Non-Goals - -- no recursive directory deletion -- no deletion of companion files or arbitrary asset contents -- no frontend-local action capability rules -- no bulk delete - -## Execution Method - -1. Extend the action enum and packer API with `DELETE` and its write message/response. -2. Add packer capability resolution for `DELETE` based on `asset.json` presence, independent from declaration validity. -3. Implement `deleteAsset` in the packer write lane. -4. Make the write path: - - resolve the asset - - delete `asset.json` - - remove the registry entry when the asset is registered - - keep the asset directory and any remaining files untouched - - patch the in-memory snapshot by removing the asset from runtime view -5. Add a Studio confirmation modal that requires the user to type the asset name exactly. -6. On success, let Studio refresh and clear the current selection. - -## Acceptance Criteria - -- `DELETE` is exposed through the packer action capability contract -- Studio renders `DELETE` only from packer-provided capabilities -- Studio requires asset-name confirmation before executing `DELETE` -- `DELETE` removes only `asset.json` -- registered assets are also removed from `index.json` -- the asset directory and remaining files stay on disk -- the runtime snapshot is updated in memory without whole-project reload in the normal path - -## Validation - -- packer tests for `DELETE` capability visibility -- packer tests for deleting registered and unregistered assets -- packer tests proving directory contents remain on disk after delete -- Studio compile/test validation for the confirmation modal and action wiring - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**` -- `prometeu-studio/src/main/java/p/studio/**` -- `prometeu-studio/src/main/resources/**` diff --git a/docs/packer/pull-requests/PR-23-move-asset-action-wizard-and-fs-first-relocation.md b/docs/packer/pull-requests/PR-23-move-asset-action-wizard-and-fs-first-relocation.md deleted file mode 100644 index de8712b2..00000000 --- a/docs/packer/pull-requests/PR-23-move-asset-action-wizard-and-fs-first-relocation.md +++ /dev/null @@ -1,101 +0,0 @@ -# PR-23 Move Asset Action Wizard and Fs-First Relocation - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The action capability track already delivers `REGISTER` and `DELETE`. - -The next operational action is `MOVE`, which must let the user relocate an asset root inside the project's `assets/` tree and optionally rename the asset directory in the same flow. - -Studio should own the wizard and the interaction flow. The packer should own the validation semantics, the filesystem move, the registry update, and the point snapshot patch after durable commit. - -## Objective - -Deliver `AssetAction.MOVE` end to end with a Studio relocation wizard, packer-owned constraints, filesystem-first directory move, and minimal in-memory snapshot update. - -## Dependencies - -- [`./PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md) -- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md) -- [`./PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md`](./PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md) - -## Scope - -- extend the public action contract and write messages for `MOVE` -- expose `MOVE` capability from the packer -- add a Studio wizard that collects: - - destination parent directory - - destination directory name - - derived target root inside `assets/` -- add a confirmation step before execution -- add an execution/waiting step with spinner while the move is running -- allow the wizard to work as both relocate and rename of the asset directory -- enforce packer constraints that: - - the target must stay inside the project's `assets/` - - the target root must not already contain `asset.json` -- perform the actual move in the filesystem inside the packer write lane -- update `index.json` and patch the runtime snapshot minimally after commit - -## Non-Goals - -- no move outside the project's `assets/` -- no directory merge behavior -- no recursive validation of non-manifest file contents -- no batch move -- no frontend-local move semantics - -## Execution Method - -1. Extend the action contract with `MOVE` and add write request/response messages for asset relocation. -2. Add packer capability resolution for `MOVE`. -3. Build a Studio wizard dedicated to move/rename, with: - - current asset root display - - destination parent picker constrained to `assets/` - - destination directory name field - - derived target root preview - - validation feedback - - confirmation step before submit - - waiting state with spinner after submit until the write result is known -4. Enforce these constraints in the packer: - - the target root must remain under `assets/` - - the target root must not already contain `asset.json` -5. Execute the move in the packer write lane by: - - moving the asset directory in the filesystem - - updating the registry entry root when the asset is registered - - preserving `asset_uuid` -6. Patch the runtime snapshot in memory after the move, without whole-project reload in the normal path. -7. Let Studio refresh and reselect the moved asset after success. -8. Keep the wizard open in waiting state while the move is running, then close only after success; on failure, leave the wizard recoverable with feedback. - -## Acceptance Criteria - -- `MOVE` is exposed through the packer action capability contract -- Studio opens a wizard for `MOVE` -- the wizard has an explicit confirmation step before execution -- the wizard enters a waiting state with spinner while the move is in flight -- the wizard lets the user relocate and/or rename the asset directory -- the move target cannot be outside the project's `assets/` -- the move target cannot already contain `asset.json` -- the packer performs the filesystem move -- `index.json` is updated when needed -- the runtime snapshot is patched minimally after success -- Studio refreshes and keeps the moved asset selected - -## Validation - -- packer tests for move capability visibility -- packer tests for successful relocate and successful rename -- packer tests for blockers when target is outside `assets/` -- packer tests for blockers when target already contains `asset.json` -- packer tests proving snapshot patching after move -- Studio smoke validation for wizard confirmation flow, waiting state, and post-move reselection - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/**` -- `prometeu-studio/src/main/java/p/studio/**` -- `prometeu-studio/src/main/resources/**` diff --git a/docs/packer/pull-requests/PR-24-asset-file-cache-hydration-and-walker-reuse.md b/docs/packer/pull-requests/PR-24-asset-file-cache-hydration-and-walker-reuse.md deleted file mode 100644 index a41b1d0b..00000000 --- a/docs/packer/pull-requests/PR-24-asset-file-cache-hydration-and-walker-reuse.md +++ /dev/null @@ -1,200 +0,0 @@ -# PR-24 Asset File Cache Hydration and Walker Reuse - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The runtime loader already walks asset roots and produces `walkResult`, and `PackerWorkspacePaths` already reserves `assets/.prometeu/cache.json`. - -What is still missing is the actual cache lifecycle: - -- previous cache is not loaded before a walk; -- walkers do not receive prior file facts for comparison; -- `walkResult` does not become a durable cache artifact after the scan. - -That leaves the current runtime path unable to reuse prior file knowledge such as `lastModified`, `size`, `fingerprint`, and family-specific probe metadata. - -This PR introduces the first durable asset file cache flow for the runtime-backed packer wave. -It also tightens how walk output becomes part of the runtime snapshot and how diagnostics are split between normal aggregated surfaces and file-scoped UI-facing surfaces. - -## Objective - -Deliver an asset-scoped file cache stored in `assets/.prometeu/cache.json`, hydrated before the runtime walk and refreshed from the current `walkResult` after the walk completes, while also attaching the current `walkResult` to the runtime snapshot. - -## Dependencies - -- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md) -- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -- [`./PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md) -- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md) -- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) -- [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -## Scope - -- define the durable schema for `assets/.prometeu/cache.json` -- store cache entries per asset and per discovered file, not as one flat global fingerprint bag -- restrict cache and internal file walk analysis to assets that are already registered and therefore have stable `asset_id` -- load prior cache state during runtime snapshot bootstrap and refresh -- pass prior asset-scoped cache entries into the asset walker -- let walkers compare current file observations against prior cached facts such as `lastModified`, `size`, `fingerprint`, and family-specific metadata -- treat the current `walkResult` as the source used to build the next durable cache state -- attach the current `walkResult` to the in-memory runtime snapshot for later query and UI use -- persist refreshed cache after a successful runtime load or write-path point patch that recomputes asset content -- keep cache miss, corruption, or version mismatch non-fatal for normal asset reads -- keep the Studio-visible asset query surface stable while the cache becomes an internal optimization and comparison input -- keep diagnostics out of the durable cache artifact -- sink general walk diagnostics into the normal asset/runtime diagnostics surface -- preserve file-scoped diagnostics as segregated walk output for UI consumers - -## Non-Goals - -- no remote/shared cache -- no final `build`/`pack` incremental pipeline -- no background watch service or external reconcile loop -- no silent reuse of stale cache entries when file identity no longer matches the current asset file -- no cache file per asset root; the baseline artifact remains the workspace-level `assets/.prometeu/cache.json` -- no UI contract that exposes raw cache internals directly to Studio -- no cache support for unregistered assets; registration remains the prerequisite for internal file analysis and durable cache ownership - -## Execution Shape - -`PR-24` should be treated as an umbrella execution plan, not as one direct implementation PR. - -This work should be split into smaller follow-up PRs so cache persistence, walker reuse policy, and runtime snapshot integration can each land with narrow tests and isolated regressions. - -## Execution Method - -1. Introduce a packer-owned cache repository around `PackerWorkspacePaths.cachePath(project)`. - The repository must load, validate, and save one workspace cache artifact without leaking raw filesystem JSON handling into loaders or walkers. - -2. Define a versioned durable cache model. - The baseline model should include: - - workspace-level schema/version fields - - asset-scoped entries keyed by stable `asset_id` - - file-scoped entries keyed by normalized relative path inside the asset root - - reusable file facts such as mime type, size, `lastModified`, content fingerprint, and family-specific probe metadata - - no persisted diagnostics; diagnostics remain runtime results produced by the current walk only - -3. Extend walker inputs so previous cache is available during content probing. - The walker contract should receive the prior asset cache view together with the declaration and asset root, rather than forcing each concrete walker to reopen cache storage on its own. - Unregistered assets do not enter this flow; they must be registered first before internal file analysis and cache ownership apply. - -4. Define cache comparison rules inside the walker layer. - Baseline rules: - - if current file `size` differs from cached `size`, cached data is invalid immediately - - if current file `lastModified` is after cached `lastModified`, cached data is invalid immediately - - content hash or fingerprint should be the last comparison step, used only when the cheaper checks do not already force invalidation and the policy still needs stronger confirmation - - if prior file facts remain valid under that ordered comparison policy, the walker may reuse prior metadata instead of recomputing everything - - if identity facts differ, the walker must treat the file as changed and emit fresh probe output - - missing prior cache is a normal cache miss, not an error - - corrupted or incompatible prior cache should surface diagnostics or operational logging as appropriate, then fall back to a cold walk - -5. Promote `walkResult` from transient scan output to cache refresh input. - After a successful walk, the loader must convert only the cacheable portions of the current `walkResult` into the next durable asset cache entry set and merge it into the workspace cache model. - Persisted cache data must be limited to reusable probe facts and metadata, never diagnostics. - -6. Attach walk output to the runtime snapshot. - The runtime snapshot should retain a dedicated runtime projection of the current walk output, not the raw probe objects themselves, so query services and Studio-facing adapters can access file-scoped probe metadata and file-scoped diagnostics without forcing a new filesystem walk. - The initial runtime posture should keep the full available file set and the subset that is currently build-eligible, plus bank-size measurement data needed by future fixed-size hardware bank checks. - The raw probe may still carry file bytes during the active walk, but the snapshot projection must strip byte payloads before retention. - The snapshot should keep inventory, probe metadata, build-candidate classification, and bank-size measurements, but not whole file contents or raw `PackerFileProbe` instances by default. - Later cleanup may reduce that retained surface, but the first implementation should prefer preserving available walk data rather than prematurely trimming it. - -7. Split diagnostic sinks intentionally. - Baseline rule: - - asset-level or walk-level diagnostics that represent the normal operational truth of the asset should flow into the usual runtime/query diagnostics sink - - file-scoped diagnostics produced by probe processing should remain segregated per file inside the walk result projection - - Studio may consume those file-scoped diagnostics for detailed UI rendering, but that segregation must not be lost by collapsing everything into one flat diagnostics list - - none of those diagnostics are persisted in `cache.json` - -8. Persist cache only at stable visibility points. - The normal runtime path should save refreshed cache after the loader finishes building a coherent snapshot. - Write-path flows that patch one asset in memory should update only the affected asset cache entry after durable commit and successful re-walk. - -9. Keep runtime snapshot and cache ownership aligned. - Runtime snapshot data may retain the current walk output needed by query services, but the durable cache artifact remains a packer-owned operational store under `assets/.prometeu/cache.json`. - -10. Emit observability only at meaningful boundaries. - The implementation may emit `cache_hit` and `cache_miss` events or counters, but adapters must not collapse cache behavior into fake asset-change semantics. - -## Acceptance Criteria - -- runtime load attempts to read `assets/.prometeu/cache.json` before walking assets -- prior asset-scoped cache entries are passed into walkers as comparison input -- cache entries are keyed by stable `asset_id`, not by asset path -- unregistered assets do not receive cache entries and do not undergo internal file analysis before registration -- walkers compare current files against prior facts using ordered checks where `size` invalidates first, `lastModified` invalidates next when the current value is newer, and fingerprint/hash remains the final expensive check -- the current walk output is attached to the in-memory runtime snapshot through a byte-free runtime projection, not through raw probe objects -- the runtime snapshot keeps enough walk data to expose available files, build-candidate files, and bank-size measurement data -- the runtime snapshot does not retain raw bytes for every discovered file by default -- normal asset/runtime diagnostics include the general walk diagnostics that should participate in the standard diagnostics surface -- file-scoped diagnostics remain segregated in the walk result projection for UI consumers -- the resulting `walkResult` is used to refresh the durable cache state -- successful runtime load writes a coherent updated cache artifact back to `assets/.prometeu/cache.json` -- missing, corrupted, or version-mismatched cache does not block snapshot load; the packer falls back to a cold walk -- point write flows that already patch one asset in memory can refresh only that asset's cache slice after commit instead of forcing full cache rebuild -- cache entries are isolated by asset and file path so one asset cannot accidentally reuse another asset's file facts -- persisted cache does not contain diagnostics from prior runs -- Studio list/details behavior remains stable and does not depend on direct cache awareness - -## Tests - -- loader tests for cold load when `cache.json` is absent -- loader tests for warm load when prior cache exists and matches current files -- loader tests for fallback when `cache.json` is malformed, unreadable, or schema-incompatible -- cache model tests proving asset cache lookup is aligned by `asset_id` -- walker tests proving changed `size` invalidates reuse immediately -- walker tests proving newer `lastModified` invalidates reuse immediately -- walker tests proving fingerprint/hash is evaluated only as the last comparison step when cheaper checks do not already invalidate reuse -- walker tests proving stable files can reuse prior metadata without changing query-visible results -- cache serialization tests proving diagnostics are never written to `cache.json` -- snapshot/query tests proving `walkResult` is attached to the runtime asset model -- tests proving general walk diagnostics sink into the normal diagnostics surface -- tests proving file-scoped diagnostics remain segregated per file for UI-facing consumers -- runtime registry tests for point cache refresh after write commit on one asset -- event or observability tests for `cache_hit` and `cache_miss` boundaries if those signals are emitted in this wave - -## Risks and Recovery - -- path-keyed cache would become unsafe during relocate flows, so the cache owner key must remain `asset_id` -- overly aggressive cache reuse can hide real content changes if comparison rules are under-specified -- saving cache at the wrong lifecycle point can publish partial truth that no coherent snapshot ever observed -- if one part of the cache flow proves unstable, recovery should disable cache hydration or persistence for that path and preserve the current cold-walk behavior until the narrower follow-up PR is corrected - -## Affected Artifacts - -- `docs/packer/pull-requests/**` -- `docs/packer/specs/2. Workspace, Registry, and Asset Identity Specification.md` -- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/PackerWorkspacePaths.java` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**` - -## Suggested Next Step - -Derive smaller implementation PRs from `PR-24`: - -1. cache model and repository - Scope: - - durable `cache.json` schema - - load/save repository - - `asset_id`-aligned cache lookup - - serialization tests proving diagnostics are excluded - -2. walker contract and comparison policy - Scope: - - previous-cache input contract - - ordered invalidation checks by `size`, then newer `lastModified`, then fingerprint/hash - - file-scoped diagnostics preservation - -3. runtime snapshot and loader integration - Scope: - - attach `walkResult` to runtime snapshot - - sink general diagnostics into the normal asset/runtime diagnostics surface - - refresh cache from the cacheable parts of `walkResult` - - point write-path refresh for one affected asset diff --git a/docs/packer/pull-requests/PR-25-asset-cache-model-and-repository.md b/docs/packer/pull-requests/PR-25-asset-cache-model-and-repository.md deleted file mode 100644 index 5e17fb04..00000000 --- a/docs/packer/pull-requests/PR-25-asset-cache-model-and-repository.md +++ /dev/null @@ -1,76 +0,0 @@ -# PR-25 Asset Cache Model and Repository - -Domain Owner: `docs/packer` - -## Briefing - -`PR-24` defines the need for a durable asset file cache in `assets/.prometeu/cache.json`, but the first executable slice should stop at cache persistence itself. - -Before walkers or runtime snapshot integration can reuse prior file facts safely, the packer needs a stable cache schema, explicit load/save ownership, and tests that prove the cache is keyed correctly and excludes non-cacheable data. - -## Objective - -Deliver the durable `cache.json` model and repository, keyed by stable `asset_id`, with no persisted diagnostics. - -## Dependencies - -- [`./PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md) -- [`./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md) -- [`../specs/2. Workspace, Registry, and Asset Identity Specification.md`](../specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md) - -## Scope - -- define the durable schema for `assets/.prometeu/cache.json` -- key asset cache ownership by stable `asset_id` -- omit unregistered assets from durable cache ownership entirely -- key file cache entries by normalized relative path inside the asset root -- persist reusable probe facts only: - - `mimeType` - - `size` - - `lastModified` - - fingerprint/hash - - family-specific metadata -- exclude diagnostics from the durable cache artifact -- add a packer-owned repository for cache load/save and schema validation - -## Non-Goals - -- no walker contract changes yet -- no cache comparison or reuse policy yet -- no runtime snapshot model changes yet -- no Studio adapter changes - -## Execution Method - -1. Add cache model types under the packer runtime model layer. -2. Define one versioned workspace cache artifact for `assets/.prometeu/cache.json`. -3. Encode asset entries by `asset_id`, never by asset root path. -4. Encode file entries by normalized asset-relative path. -5. Add repository load/save behavior with safe fallback on missing or invalid cache files. -6. Prove by tests that diagnostics cannot be serialized into the durable cache artifact. - -## Acceptance Criteria - -- the packer has explicit model types for the durable cache artifact -- cache ownership is keyed by `asset_id` -- unregistered assets do not receive durable cache entries -- file cache entries are keyed by normalized relative file path -- repository load on absent cache returns a safe empty state -- malformed or schema-incompatible cache can be rejected cleanly without crashing the runtime load path -- diagnostics are not part of the serialized cache schema - -## Validation - -- schema serialization tests for workspace cache -- repository round-trip tests for valid cache content -- repository tests for absent cache file -- repository tests for malformed cache file -- cache model tests proving `asset_id`-aligned lookup -- serialization tests proving diagnostics are excluded from `cache.json` - -## Affected Artifacts - -- `docs/packer/pull-requests/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**` diff --git a/docs/packer/pull-requests/PR-26-walker-cache-input-and-comparison-policy.md b/docs/packer/pull-requests/PR-26-walker-cache-input-and-comparison-policy.md deleted file mode 100644 index 87e8a148..00000000 --- a/docs/packer/pull-requests/PR-26-walker-cache-input-and-comparison-policy.md +++ /dev/null @@ -1,71 +0,0 @@ -# PR-26 Walker Cache Input and Comparison Policy - -Domain Owner: `docs/packer` - -## Briefing - -Once the durable cache model exists, the next narrow step is to let walkers consume prior cached file facts without coupling them to cache storage. - -This PR defines the cache-aware walker contract and the ordered invalidation policy that decides when prior metadata can be reused and when a fresh probe is mandatory. - -## Objective - -Deliver walker-side prior-cache input and a deterministic comparison policy ordered by `size`, then newer `lastModified`, then fingerprint/hash. - -## Dependencies - -- [`./PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md) -- [`./PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md) - -## Scope - -- extend walker inputs so they receive prior asset cache state -- keep walkers independent from cache repository I/O -- apply walker-side internal file analysis only to already-registered assets -- define ordered invalidation checks: - - changed `size` invalidates immediately - - newer `lastModified` invalidates immediately - - fingerprint/hash is evaluated last when stronger confirmation is still needed -- allow walkers to reuse prior metadata when cached facts remain valid -- preserve file-scoped diagnostics in walk output - -## Non-Goals - -- no runtime snapshot attachment yet -- no cache persistence integration in the loader yet -- no point write-path refresh yet -- no Studio UI contract changes - -## Execution Method - -1. Update walker contracts to accept prior asset cache input together with asset root and declaration. -2. Keep cache lookup outside concrete walkers; they should receive an already-resolved asset cache view. -3. Implement the ordered invalidation policy in the shared walker path. -4. Reuse prior metadata only when the ordered checks keep the cached entry valid. -5. Preserve file-scoped diagnostics in the resulting walk output for later runtime and UI consumption. - -## Acceptance Criteria - -- walkers receive prior asset cache entries as input -- the walker layer does not perform cache repository I/O directly -- unregistered assets are excluded from internal file analysis and cache-aware walker reuse -- changed `size` invalidates prior reuse immediately -- newer `lastModified` invalidates prior reuse immediately -- fingerprint/hash remains the final expensive comparison step -- stable files may reuse prior metadata without changing query-visible semantics -- file-scoped diagnostics remain segregated in walk output - -## Validation - -- walker tests proving changed `size` invalidates reuse -- walker tests proving newer `lastModified` invalidates reuse -- walker tests proving fingerprint/hash is only evaluated after cheaper checks do not already invalidate reuse -- walker tests proving stable files can reuse prior metadata -- tests proving file-scoped diagnostics remain attached to per-file walk output - -## Affected Artifacts - -- `docs/packer/pull-requests/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**` diff --git a/docs/packer/pull-requests/PR-27-runtime-walkresult-and-cache-integration.md b/docs/packer/pull-requests/PR-27-runtime-walkresult-and-cache-integration.md deleted file mode 100644 index d8a55831..00000000 --- a/docs/packer/pull-requests/PR-27-runtime-walkresult-and-cache-integration.md +++ /dev/null @@ -1,88 +0,0 @@ -# PR-27 Runtime WalkResult and Cache Integration - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -With cache persistence and walker reuse policy isolated, the final slice is to connect them to the runtime model. - -This PR makes the runtime loader hydrate prior cache before the walk, attach the current `walkResult` to the in-memory snapshot, sink general diagnostics into the normal diagnostics surface, preserve file-scoped diagnostics for UI consumers, and refresh the durable cache from the cacheable portions of the current walk. - -## Objective - -Deliver runtime-side integration of prior cache hydration, `walkResult` snapshot attachment, diagnostics sink split, and refreshed cache persistence. - -## Dependencies - -- [`./PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md) -- [`./PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md) -- [`./PR-26-walker-cache-input-and-comparison-policy.md`](./PR-26-walker-cache-input-and-comparison-policy.md) -- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md) -- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -## Scope - -- load prior `cache.json` during runtime snapshot bootstrap and refresh -- resolve prior cache by `asset_id` before invoking the walker -- attach a byte-free runtime projection of the current `walkResult` to the in-memory runtime asset model -- retain enough walk data in the runtime snapshot to inspect available files, build-candidate files, and bank-size measurement data -- avoid retaining raw file bytes for the full discovered file set in the runtime snapshot -- sink general walk diagnostics into the normal asset/runtime diagnostics surface -- preserve file-scoped diagnostics as segregated walk output for UI consumers -- refresh and persist cache from the cacheable portions of the current walk -- support point cache refresh for one affected asset after successful write commit and re-walk - -## Non-Goals - -- no new Studio feature surface beyond exposing already-owned file-scoped walk data -- no background reconcile observer -- no build/incremental pipeline work - -## Execution Method - -1. Load prior workspace cache at runtime bootstrap and on refresh. -2. Resolve the current asset cache slice by `asset_id` and pass it into the walker. - Assets without `asset_id` are outside this flow and should not receive internal file analysis or cache ownership. -3. Attach a dedicated runtime projection of the current `walkResult` to the runtime snapshot model. - The first implementation should keep the available file set, the build-candidate subset, and bank-size measurement data accessible from the snapshot instead of optimizing that shape away early. - The runtime projection should drop raw file bytes and should not retain raw `PackerFileProbe` objects unless a narrower later use case proves they are needed. -4. Route general walk diagnostics into the standard asset/runtime diagnostics sink. -5. Preserve file-scoped diagnostics inside the walk result projection used by later query/UI consumers. -6. Persist refreshed cache after coherent runtime load completes. -7. Reuse the same logic to refresh one asset cache slice after successful point write commit and re-walk. - -## Acceptance Criteria - -- runtime load reads prior cache before invoking walkers -- cache lookup passed to the walker is aligned by `asset_id` -- assets without `asset_id` are excluded from cache ownership and internal file analysis -- runtime assets retain a byte-free projection of the current walk output in memory -- runtime assets retain enough walk data to inspect available files, build-candidate files, and bank-size measurement data -- runtime snapshot retention excludes raw file bytes for the general discovered file set -- general walk diagnostics appear in the normal diagnostics surface -- file-scoped diagnostics remain segregated for detailed consumers -- refreshed cache written after runtime load contains only cacheable probe facts and metadata -- point write flows can refresh only one affected asset cache entry after commit -- missing, malformed, or incompatible cache falls back to cold walk without blocking runtime queries - -## Validation - -- loader tests for cold load without cache -- loader tests for warm load with cache hydration -- snapshot/query tests proving `walkResult` is attached to runtime assets -- diagnostics tests proving general sink aggregation and file-scoped segregation -- cache refresh tests proving the durable artifact is rebuilt from cacheable walk data only -- runtime registry tests for one-asset cache refresh after point write commit - -## Affected Artifacts - -- `docs/packer/pull-requests/**` -- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**` -- `prometeu-studio/**` query adapter coverage when file-scoped diagnostics become consumable diff --git a/docs/packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md b/docs/packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md deleted file mode 100644 index 03b336f4..00000000 --- a/docs/packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md +++ /dev/null @@ -1,107 +0,0 @@ -# PR-28 Pack Wizard Public Contracts: Summary, Validation, and Execution - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The Studio `Pack Wizard` decision is now closed on the host side. - -That decision makes the intended boundary explicit: - -- Studio is a shell; -- packer owns summary, validation, pack execution, progress, and result semantics; -- the Studio-facing flow depends on three distinct calls: - `summary`, `validation`, and `pack execution`. - -This PR creates the packer-side public contracts needed for that flow. - -Reference decision: - -- [`../../studio/decisions/Pack Wizard in Assets Workspace Decision.md`](../../studio/decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md) - -## Objective - -Add public packer contracts for pack summary, pack validation, and pack execution so Studio can bind the wizard flow without inventing local semantics. - -## Dependencies - -- [`../agendas/Pack Wizard Studio Decision Propagation Agenda.md`](../agendas/Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md) -- [`./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md) -- [`./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md`](./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md) -- [`./PR-08-assets-pa-and-companion-artifact-emission.md`](./PR-08-assets-pa-and-companion-artifact-emission.md) - -## Scope - -- extend `PackerWorkspaceService` with three explicit public operations: - - pack summary - - pack validation - - pack execution -- add request/response messages for those operations in `prometeu-packer-api` -- add public DTOs required by those responses -- reuse existing API concepts wherever already adequate instead of cloning parallel concepts -- define result shapes that Studio can bind directly for: - - `Summary` - - `Validation` - - `Result` -- keep progress ownership aligned with the existing event-based packer operational model - -## Non-Goals - -- no full `prometeu-packer-v1` implementation of summary, validation, or pack execution in this PR -- no Studio wizard implementation in this PR -- no cancellation contract in the first wave -- no speculative build-session abstraction -- no duplication of existing diagnostics DTOs if current public DTOs already satisfy the need - -## Execution Method - -1. Audit current public API shapes in `prometeu-packer-api` and reuse existing patterns for request/result naming, status, diagnostics, and progress. -2. Extend `PackerWorkspaceService` with three explicit methods that match the Studio decision boundary. -3. Add request/result messages under `p.packer.messages` for: - - summary - - validation - - pack execution -4. Add focused DTOs under the public API for: - - pack summary aggregate - - pack validation aggregate - - pack validation per-asset entry - - emitted artifact summary - - final pack execution summary -5. Reuse existing public diagnostics DTOs for validation drill-down where possible. -6. Keep progress delivery on the existing event path instead of embedding a second progress protocol into result DTOs. -7. Keep naming aligned with the canonical artifact terminology `assets.pa`. - -## Contract Direction - -The new public surface should make these distinctions explicit: - -1. summary is read-only preflight information about the current pack set; -2. validation is dry-run-like and non-emitting; -3. pack execution is the only operation that emits artifacts; -4. the pack set is the current `registered + included in build` set; -5. blocking diagnostics in that set make validation unsuccessful. - -## Acceptance Criteria - -- `PackerWorkspaceService` exposes three distinct public methods for summary, validation, and pack execution -- the public API includes request/result messages for all three operations -- public DTOs exist for the Studio wizard to render summary, validation, and final result -- existing public diagnostics DTOs are reused where appropriate instead of duplicated -- progress remains aligned with the packer event model rather than a new ad hoc progress response shape -- the contract language uses `assets.pa` as the canonical emitted artifact name - -## Validation - -- compile-level validation that `prometeu-packer-api` exposes the new methods and DTOs coherently -- public API review for naming and reuse consistency -- contract-focused tests if lightweight API tests already exist for public message shapes -- Studio-side binding review to confirm the API is sufficient without local semantic reconstruction - -## Affected Artifacts - -- `docs/packer/agendas/**` -- `docs/packer/pull-requests/**` -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/PackerWorkspaceService.java` -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/**` -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/dtos/**` diff --git a/docs/packer/pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md b/docs/packer/pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md deleted file mode 100644 index 3a17e1b2..00000000 --- a/docs/packer/pull-requests/PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md +++ /dev/null @@ -1,93 +0,0 @@ -# PR-29 Pack Wizard Contract Adjustments for Summary and Validation - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The first public contract wave for the `Pack Wizard` has already landed in `prometeu-packer-api`, but the newly accepted packer decision for `summary` and `validation` closes a more specific shape than the initial API slice. - -In particular: - -- `summary` is no longer aggregate-only; -- `summary` must expose a per-asset list for the active pack set; -- `validation` is primarily a per-asset blocking-diagnostics list; -- `validation` ordering is not a packer concern in the first wave; -- aggregate validation data is secondary, not the center of the contract. - -This PR adjusts the public contracts so they match the accepted packer decision exactly. - -Reference decision: - -- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md) - -## Objective - -Align the public `prometeu-packer-api` contract for `summary` and `validation` with the accepted decision before deeper implementation work continues. - -## Dependencies - -- [`./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md) -- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md) -- cross-domain reference: - [`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md) - -## Scope - -- adjust the public summary DTOs to include: - - aggregate included asset count - - per-asset summary list -- adjust the public validation DTOs to make the per-asset blocking-diagnostics list the primary payload -- add or rename DTOs as needed for: - - per-asset summary entry - - per-asset validation entry -- keep `lastModified` present in both summary and validation item contracts -- preserve the `read-only` and `non-mutating` nature of summary and validation -- keep the Studio-facing API explicit and aligned with the accepted packer decision - -## Non-Goals - -- no runtime implementation of summary in `prometeu-packer-v1` -- no runtime implementation of validation in `prometeu-packer-v1` -- no `pack execution` contract changes unless strictly required by compile compatibility -- no Studio implementation work in this PR - -## Execution Method - -1. Revisit the current `summary` and `validation` public DTOs in `prometeu-packer-api`. -2. Expand the summary result shape so it carries: - - total included asset count - - per-asset summary entries -3. Expand or reshape validation so the returned per-asset entries expose: - - asset id - - asset name - - asset path - - `lastModified` - - blocking diagnostics -4. Keep validation aggregate data optional or secondary rather than the primary response focus. -5. Preserve defensive-copy and validation patterns already used by public API records. -6. Update Studio compile surfaces only as needed to keep the workspace consuming the revised contracts coherently. - -## Acceptance Criteria - -- the public summary contract matches the accepted decision shape -- the public validation contract matches the accepted decision shape -- `lastModified` exists in both per-asset summary and per-asset validation entries -- validation payloads carry blocking diagnostics only in the first wave -- compile succeeds across `prometeu-packer-api`, `prometeu-packer-v1`, and any directly affected Studio call sites - -## Validation - -- compile validation for `prometeu-packer-api` -- compile validation for `prometeu-packer-v1` -- compile validation for `prometeu-studio` -- lightweight API tests if public message-shape tests already exist - -## Affected Artifacts - -- `docs/packer/decisions/**` -- `docs/packer/pull-requests/**` -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/PackerWorkspaceService.java` -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/**` -- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/dtos/**` -- `prometeu-studio/**` compile-level consumers of the summary/validation contracts diff --git a/docs/packer/pull-requests/PR-30-pack-wizard-summary-snapshot-query.md b/docs/packer/pull-requests/PR-30-pack-wizard-summary-snapshot-query.md deleted file mode 100644 index f6403912..00000000 --- a/docs/packer/pull-requests/PR-30-pack-wizard-summary-snapshot-query.md +++ /dev/null @@ -1,83 +0,0 @@ -# PR-30 Pack Wizard Summary Snapshot Query - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -With the public contracts aligned, the next step is to actually produce the pack-wizard `summary` from the packer runtime snapshot. - -This is intentionally narrower than full pack execution. -The goal is to expose a fast preflight summary of the active pack set so the Studio wizard can open on packer-owned state instead of local UI heuristics. - -Reference decision: - -- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md) - -## Objective - -Implement snapshot-backed `summary` for the pack wizard over the current `registered + included in build` set. - -## Dependencies - -- [`./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md) -- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md) -- cross-domain reference: - [`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md) - -## Scope - -- implement `getPackWorkspaceSummary(...)` in `prometeu-packer-v1` -- resolve the active pack set from the runtime snapshot: - `registered + included in build` -- produce the aggregate included asset count -- produce the per-asset summary list with: - - asset id - - asset name - - asset family - - min artifact count - - max artifact count - - `lastModified` -- allow `lastModified = 0` in the first wave where the real value is not yet available -- keep the query fast and snapshot-backed - -## Non-Goals - -- no validation logic in this PR -- no pack execution logic in this PR -- no emitted-artifact preview in summary -- no inclusion of unregistered or excluded assets as explicit summary items - -## Execution Method - -1. Resolve the active runtime snapshot for the requested project. -2. Filter the snapshot to the active pack set: - registered assets included in build. -3. Derive one aggregate count from that filtered set. -4. Map each included asset into the public per-asset summary DTO. -5. Populate `minArtifactCount` and `maxArtifactCount` from the best currently available packer-owned summary facts. -6. Populate `lastModified` from packer-owned runtime or filesystem facts when available, otherwise `0`. -7. Return the summary result without performing deep validation or artifact planning. - -## Acceptance Criteria - -- `getPackWorkspaceSummary(...)` returns successfully from snapshot-backed state -- the returned set contains only `registered + included in build` assets -- the aggregate count matches the per-asset list size -- per-asset summary entries expose the fields required by the accepted decision -- the operation behaves as a fast read query rather than a deep recomputation path - -## Validation - -- packer unit tests for pack-set filtering -- packer unit tests for summary DTO mapping -- regression tests proving excluded and unregistered assets do not appear as summary items -- Studio smoke validation proving the wizard summary can render from packer-owned data - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**` -- `prometeu-studio/**` wizard summary consumer surfaces if compile adaptation is needed diff --git a/docs/packer/pull-requests/PR-31-pack-wizard-validation-snapshot-gate.md b/docs/packer/pull-requests/PR-31-pack-wizard-validation-snapshot-gate.md deleted file mode 100644 index 135e1771..00000000 --- a/docs/packer/pull-requests/PR-31-pack-wizard-validation-snapshot-gate.md +++ /dev/null @@ -1,91 +0,0 @@ -# PR-31 Pack Wizard Validation Snapshot Gate - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The `Pack Wizard` validation phase is not a generic workspace scan. -It is a pack-set-specific gate over the current `registered + included in build` snapshot state. - -The accepted decision closes the first-wave semantics: - -- validation is read-only and snapshot-backed; -- validation looks only at the active pack set; -- only `blocking` diagnostics fail validation; -- the primary payload is the per-asset blocking-diagnostics list. - -This PR implements that gate in `prometeu-packer-v1`. - -Reference decision: - -- [`../decisions/Pack Wizard Summary and Validation Contracts Decision.md`](../decisions/Pack%20Wizard%20Summary%20and%20Validation%20Contracts%20Decision.md) - -## Objective - -Implement snapshot-backed pack validation that returns per-asset blocking diagnostics for the active pack set and decides whether packing may proceed. - -## Dependencies - -- [`./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md) -- [`./PR-30-pack-wizard-summary-snapshot-query.md`](./PR-30-pack-wizard-summary-snapshot-query.md) -- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -- cross-domain reference: - [`../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md`](../../studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md) - -## Scope - -- implement `validatePackWorkspace(...)` in `prometeu-packer-v1` -- evaluate only the current `registered + included in build` set from the runtime snapshot -- collect only `blocking` diagnostics for the first-wave validation payload -- return per-asset validation entries with: - - asset id - - asset name - - asset path - - `lastModified` - - blocking diagnostics -- make validation green when no blocking diagnostics are returned -- make validation red when any blocking diagnostics are returned -- keep aggregate validation data secondary to the per-asset list - -## Non-Goals - -- no pack execution in this PR -- no non-blocking diagnostics in the first-wave validation payload -- no packer-owned ordering contract for the returned validation list -- no deep-sync orchestration in this PR beyond using the current snapshot boundary - -## Execution Method - -1. Resolve the current runtime snapshot for the requested project. -2. Filter it to the active pack set: - `registered + included in build`. -3. Gather diagnostics relevant to each asset in that set. -4. Keep only diagnostics marked `blocking` for the first-wave validation response. -5. Map each asset with blockers into the public per-asset validation DTO. -6. Allow `lastModified = 0` temporarily where the real value is not yet available. -7. Return validation as green when the per-asset blocker list is empty and red otherwise. - -## Acceptance Criteria - -- `validatePackWorkspace(...)` evaluates only the active pack set -- only blocking diagnostics appear in the first-wave validation payload -- validation succeeds when no blocking diagnostics are present -- validation fails when any blocking diagnostics are present -- per-asset validation entries expose the fields required by the accepted decision -- Studio can stop before `Packing` using packer-owned validation alone - -## Validation - -- packer unit tests for pack-set filtering during validation -- packer unit tests proving non-blocking diagnostics do not fail the first-wave validation -- packer unit tests proving blocking diagnostics do fail validation -- DTO-mapping tests for per-asset validation entries -- Studio smoke validation proving the wizard blocks on returned blockers - -## Affected Artifacts - -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**` -- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**` -- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**` -- `prometeu-studio/**` validation consumer surfaces if compile adaptation is needed diff --git a/docs/packer/pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md b/docs/packer/pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md deleted file mode 100644 index d3022a39..00000000 --- a/docs/packer/pull-requests/PR-32-palette-declarations-with-explicit-index-contract.md +++ /dev/null @@ -1,113 +0,0 @@ -# PR-32 Palette Declarations with Explicit Index Contract - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio`, `../runtime` - -## Briefing - -The current authoring shape for `asset.json.output.pipeline.palettes` is still too dependent on list order as semantic identity. - -That is fragile: - -- editorial reordering can silently change meaning; -- merges become harder to review safely; -- the packer has to infer identity from position instead of reading it explicitly. - -The repository already depends on stable palette ordering for `tile bank` packing. -That ordering should therefore be explicit in the authoring contract. - -## Decisions de Origem - -- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md) -- ongoing agenda: - [`../agendas/Tile Bank Packing Materialization Agenda.md`](../agendas/Tile%20Bank%20Packing%20Materialization%20Agenda.md) - -## Objective - -Replace list-position-defined palette identity with an explicit index-bearing declaration contract for `asset.json.output.pipeline.palettes`. - -Recommended shape: - -```json -"palettes": [ - { - "index": 0, - "palette": { ... } - }, - { - "index": 1, - "palette": { ... } - } -] -``` - -## Dependencies - -- tile-bank materialization agenda in `docs/packer/agendas` -- runtime-side tile-bank consumer contract already aligned around stable palette ids - -## Scope - -- define the normative authoring shape for `output.pipeline.palettes` -- make `index` the semantic identity of each declared palette -- require packer normalization to sort by `index`, not by list position -- define diagnostics for duplicate, missing, invalid, or malformed palette entries -- prepare propagation into: - - packer specs - - parser/runtime-facing normalization code - - Studio editing surfaces if they expose palette management - -## Non-Goals - -- no immediate migration of `artifacts` in this PR -- no tile-bank payload implementation in this PR -- no runtime code changes in this PR -- no speculative keyed-object JSON contract for palettes in this wave - -## Execution Method - -1. Update the packer-side documentation/decision chain to make palette identity explicit. -2. Define `output.pipeline.palettes` as a list of records with: - - `index` - - `palette` -3. State that semantic ordering is ascending numeric `index`, never raw list position. -4. Define structural diagnostics: - - duplicate `index` => blocking - - negative or malformed `index` => blocking - - missing `palette` payload => blocking - - palette count above the runtime-facing v1 limit => blocking -5. Define whether index gaps are: - - blocking - - or warning/advisory -6. Prepare follow-up implementation PRs for parser, validation, and Studio surfaces. - -## Contract Direction - -First-wave packer contract direction: - -1. `output.pipeline.palettes` remains a JSON array for authoring ergonomics; -2. each entry must declare an explicit `index`; -3. each entry must declare a `palette` object payload; -4. packer meaning comes from numeric `index`, not from the physical array position; -5. the runtime-facing `palette_id` consumed later by tile/sprite draw paths is the normalized numeric palette `index`. - -## Acceptance Criteria - -- the packer docs/spec path no longer relies on raw list order as palette identity -- the explicit-index palette shape is documented clearly enough for parser and Studio implementation -- duplicate or malformed palette indices are identified as structural diagnostics -- the contract leaves no ambiguity about whether sorting happens by array order or by `index` - -## Validation - -- editorial validation across packer agenda/decision/spec material -- parser-oriented review proving the contract is implementable without hidden heuristics -- Studio-facing review confirming the editing UX can preserve stable palette identity - -## Affected Artifacts - -- `docs/packer/agendas/**` -- `docs/packer/decisions/**` -- `docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md` -- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md` -- future parser/runtime materialization code under `prometeu-packer-v1` diff --git a/docs/packer/pull-requests/PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md b/docs/packer/pull-requests/PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md deleted file mode 100644 index 1d8927c4..00000000 --- a/docs/packer/pull-requests/PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md +++ /dev/null @@ -1,80 +0,0 @@ -# PR-33 Tile Bank Spec Propagation and Runtime Contract Alignment - -Domain Owner: `docs/packer` -Cross-Domain Impact: `../runtime`, `docs/studio` - -## Briefing - -The `Tile Bank Packing Materialization Decision` is now closed. - -Before more code lands, the normative spec path needs to be updated so implementation is not forced to infer format details from agendas and decisions. - -This PR is editorial-first. -Its job is to propagate the accepted tile-bank producer contract into the relevant packer specs and to make the runtime alignment explicit. - -## Objective - -Update the normative spec corpus so `tile bank` v1 packing has one unambiguous producer contract. - -## Dependencies - -- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md) -- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md) -- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md) -- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md) - -## Scope - -- propagate the accepted `tile bank` v1 contract into packer specs -- define canonical payload semantics for `TILES/indexed_v1` -- define metadata convergence shape for tile-bank runtime entries -- make runtime-aligned size and decoded-size formulas explicit -- document the fixed `256 x 256` target and row-major slot semantics - -## Non-Goals - -- no production code changes -- no walker refactor -- no payload emitter implementation -- no runtime implementation work - -## Method - -1. Update [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md). -2. Define `TILES/indexed_v1` producer semantics explicitly: - - `1 artifact = 1 tile` - - `tile_id = normalized artifacts[*].index` - - fixed `256 x 256` emitted sheet - - row-major placement - - packed `u4` pixel plane - - `64 * 16 * u16` RGB565 palette block -3. Document runtime entry derivation: - - `bank_type = TILES` - - `codec = NONE` - - `size = ceil(width * height / 2) + 2048` - - `decoded_size = (width * height) + 2048` -4. Document metadata normalization: - - `output.metadata -> metadata` - - `output.codec_configuration -> metadata.codec` - - `output.pipeline -> metadata.pipeline` -5. Cross-reference the runtime-side metadata normalization discussion without pretending it is already closed there. - -## Acceptance Criteria - -- the packer spec corpus contains one explicit producer contract for tile-bank v1 -- the payload shape no longer needs to be reconstructed from agenda text -- size, decoded-size, palette count, and metadata shape are all normative -- the spec states what the producer emits because that is what the consumer requires - -## Validation - -- editorial review against the accepted decision -- consistency check against runtime specs and loader assumptions -- terminology review for `tile_id`, `palette_id`, `size`, `decoded_size`, and metadata segmentation - -## Affected Artifacts - -- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md` -- possibly `docs/packer/specs/1. Domain and Artifact Boundary Specification.md` -- possibly `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md` - diff --git a/docs/packer/pull-requests/PR-34-tile-bank-diagnostics-and-validation-hardening.md b/docs/packer/pull-requests/PR-34-tile-bank-diagnostics-and-validation-hardening.md deleted file mode 100644 index 104762e5..00000000 --- a/docs/packer/pull-requests/PR-34-tile-bank-diagnostics-and-validation-hardening.md +++ /dev/null @@ -1,75 +0,0 @@ -# PR-34 Tile Bank Diagnostics and Validation Hardening - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -The tile-bank decision closed the structural blockers and warnings that must exist before pack emission. - -Those diagnostics belong in the walker/materialization path so they surface during validation and are naturally rerun by `packWorkspace(...)` when a fresh frozen snapshot is created. - -This PR isolates that diagnostic work from payload emission. - -## Objective - -Add the accepted tile-bank diagnostics to the packer walk/materialization path and make validation consume them consistently. - -## Dependencies - -- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md) -- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md) -- `PR-33` for normative spec propagation - -## Scope - -- add tile-bank structural blocking diagnostics -- add tile-bank warning diagnostics for fragile indices -- ensure those diagnostics live in the walker/materialization path -- ensure validation consumes them without special late pack-only logic - -## Non-Goals - -- no full payload emission yet -- no staging/promote pipeline yet -- no shipper behavior -- no future multi-tile-per-artifact support - -## Method - -1. Add blocking diagnostics for: - - duplicate `artifacts[*].index` - - gaps in normalized artifact indices - - fixed-sheet capacity overflow - - banks without declared palettes - - palette declaration count above `64` - - malformed palette declarations - - missing or invalid required tile-bank metadata - - failures to normalize artifacts into deterministic tile candidates -2. Add `WARNING` diagnostics for fragile tile indices across the full declared bank palette set. -3. Ensure diagnostics are attached at file/asset walk time so: - - `GetAssetDetails` - - `ValidatePackWorkspace` - - future pack rerun gate - all see the same structural findings. -4. Add tests that distinguish blocking failures from advisory warnings. - -## Acceptance Criteria - -- validation returns blocked tile-bank assets when any accepted blocker exists -- fragile-index findings are visible but do not block by themselves -- no tile-bank structural problem is discovered only during final byte emission -- the same diagnostic vocabulary is visible in details and validation paths - -## Validation - -- targeted service and walker tests -- validation-flow regression tests -- asset-details regression tests for warning and blocking surfaces - -## Affected Artifacts - -- `prometeu-packer-v1` tile-bank walker/materialization code -- `prometeu-packer-v1` validation/query services -- related tests under `prometeu-packer-v1/src/test` - diff --git a/docs/packer/pull-requests/PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md b/docs/packer/pull-requests/PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md deleted file mode 100644 index 0932f57d..00000000 --- a/docs/packer/pull-requests/PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md +++ /dev/null @@ -1,69 +0,0 @@ -# PR-35 Packing-Aware Walkers and Runtime Materialization Preparation - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio` - -## Briefing - -Pack execution now depends on a frozen in-memory execution snapshot, but the repository deliberately chose not to fork discovery into one runtime walker stack and one packing walker stack. - -This PR prepares the existing walker/materialization path so it can serve both runtime reads and pack execution with explicit policy. - -## Objective - -Prepare walkers and runtime materialization for packing-aware projection without implementing final pack emission yet. - -## Dependencies - -- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md) -- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md) -- `PR-34` for diagnostics already present in the walk/materialization path - -## Scope - -- add optional content bytes to runtime walk projection -- introduce or finish the accepted materialization config/policy shape -- keep family walkers discovery-oriented -- enable packing-focused projection filtering over discovered probes -- make build-relevant content bytes available for packing snapshots only - -## Non-Goals - -- no final `packWorkspace(...)` implementation yet -- no staging/promotion yet -- no tile-bank payload bytes emitted yet -- no alternative walker stack - -## Method - -1. Add `Optional` support to `PackerRuntimeWalkFile`. -2. Ensure full probes can still carry bytes internally during discovery. -3. Materialize runtime projection using explicit config/policy: - - runtime mode suppresses optional bytes - - packing mode injects optional bytes - - projection filter keeps only build-relevant selected probes -4. Keep family walkers focused on relevance-by-family. -5. Add tests showing: - - runtime default projection does not retain bytes - - packing projection retains bytes only for relevant selected files - - the same discovery path serves both modes - -## Acceptance Criteria - -- the repository has one walker discovery path, not two divergent ones -- packing projection can freeze build-relevant bytes in memory -- runtime-backed reads do not become wasteful full-memory mirrors -- selected build inputs survive into runtime walk projection with optional bytes when packing mode is requested - -## Validation - -- targeted runtime materialization tests -- walker reuse regression tests -- cache integration review where relevant - -## Affected Artifacts - -- `prometeu-packer-v1` walker models -- `prometeu-packer-v1` runtime materializer/export path -- related tests under `prometeu-packer-v1/src/test` - diff --git a/docs/packer/pull-requests/PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md b/docs/packer/pull-requests/PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md deleted file mode 100644 index 9bfe5333..00000000 --- a/docs/packer/pull-requests/PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md +++ /dev/null @@ -1,86 +0,0 @@ -# PR-36 Pack Workspace Execution with Frozen Snapshot and Staging - -Domain Owner: `docs/packer` -Cross-Domain Impact: `docs/studio`, `../runtime` - -## Briefing - -After specs, diagnostics, and packing-aware materialization are in place, the remaining step is the actual pack execution pipeline. - -This PR implements `packWorkspace(...)` as the first end-to-end writer that: - -- reruns the gate on a fresh execution snapshot; -- materializes build outputs from frozen in-memory inputs; -- stages outputs before promotion; -- and publishes coherent final artifacts to `build/`. - -## Objective - -Implement the first-wave `packWorkspace(...)` pipeline with frozen snapshot input, tile-bank payload emission, and staged publication. - -## Dependencies - -- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md) -- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md) -- `PR-33` -- `PR-34` -- `PR-35` - -## Scope - -- implement pack rerun gate on a fresh execution snapshot -- materialize tile-bank payload bytes from frozen in-memory inputs -- emit `assets.pa` and companion outputs in staging -- promote staged outputs into final `build/` locations only on coherent success -- return structured pack results for blocked, failed, and successful outcomes - -## Non-Goals - -- no shipper packaging or `.pbc` generation -- no remote or incremental build behavior -- no cancellation semantics -- no non-tile-bank payload families unless they are already trivial and fully decided - -## Method - -1. Create a fresh frozen execution snapshot for the current included-in-build set. -2. Rerun the pack validation gate on that snapshot before byte emission begins. -3. For tile banks: - - normalize selected artifacts into one row-major `256 x 256` sheet - - pack tile pixels as `u4` - - emit the `64 * 16 * 2` RGB565 palette block - - derive runtime entry metadata using the accepted segmentation contract -4. Emit staged outputs under `build/.staging//`. -5. Promote staged outputs into: - - `build/assets.pa` - - `build/asset_table.json` - - `build/preload.json` - - `build/asset_table_metadata.json` -6. Return structured terminal results that distinguish: - - gate failure - - execution/materialization failure - - persistence/promotion failure - -## Acceptance Criteria - -- `packWorkspace(...)` never emits from live filesystem rereads after frozen snapshot creation -- gate rerun blocks stale-invalid projects even if validation was green earlier -- failed execution before promotion does not leave partial final build outputs visible as success -- successful execution publishes coherent final build outputs -- tile-bank payload bytes satisfy the accepted producer contract and runtime consumer assumptions - -## Validation - -- targeted `packWorkspace(...)` service tests -- tile-bank conformance tests from artifacts to emitted payload -- staging/promotion failure-path tests -- regression tests for blocked vs failed vs successful results - -## Affected Artifacts - -- `prometeu-packer-api` pack result contract -- `prometeu-packer-v1` pack execution service -- `prometeu-packer-v1` tile-bank payload materializer -- `prometeu-packer-v1` staging/promote pipeline -- related tests under `prometeu-packer-v1/src/test` - diff --git a/docs/packer/pull-requests/README.md b/docs/packer/pull-requests/README.md index cee9da53..f834d9f8 100644 --- a/docs/packer/pull-requests/README.md +++ b/docs/packer/pull-requests/README.md @@ -2,6 +2,12 @@ This directory contains self-contained packer change proposals for review. +Current retained set: + +- none + +The previous execution wave has already been consolidated into [`../learn/`](../learn/) and propagated into [`../specs/`](../specs/). + ## Purpose A pull request document packages a packer change as an executable plan before final integration. @@ -58,52 +64,5 @@ A pull request may plan code and spec consequences, but it must not replace a mi ## Production Sequence -The current production track for the standalone `prometeu-packer` project is: - -1. [`PR-01-packer-project-bootstrap-and-module-boundaries.md`](./PR-01-packer-project-bootstrap-and-module-boundaries.md) -2. [`PR-02-workspace-init-registry-and-identity-foundation.md`](./PR-02-workspace-init-registry-and-identity-foundation.md) -3. [`PR-03-asset-declaration-parsing-validation-and-details-contract.md`](./PR-03-asset-declaration-parsing-validation-and-details-contract.md) -4. [`PR-04-workspace-scan-list-assets-and-studio-read-adapter.md`](./PR-04-workspace-scan-list-assets-and-studio-read-adapter.md) -5. [`PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](./PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md) -6. [`PR-06-doctor-diagnostics-and-safe-fix-baseline.md`](./PR-06-doctor-diagnostics-and-safe-fix-baseline.md) -7. [`PR-07-build-plan-determinism-and-cache-key-foundation.md`](./PR-07-build-plan-determinism-and-cache-key-foundation.md) -8. [`PR-08-assets-pa-and-companion-artifact-emission.md`](./PR-08-assets-pa-and-companion-artifact-emission.md) -9. [`PR-09-event-lane-progress-and-studio-operational-integration.md`](./PR-09-event-lane-progress-and-studio-operational-integration.md) -10. [`PR-10-versioning-migration-trust-and-production-gates.md`](./PR-10-versioning-migration-trust-and-production-gates.md) -11. [`PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md`](./PR-11-packer-runtime-restructure-snapshot-authority-and-durable-commit.md) -12. [`PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md`](./PR-12-cleanup-and-unused-surface-removal-before-runtime-service-wave.md) -13. [`PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md`](./PR-13-embedded-bootstrap-container-owned-event-bus-and-packer-composition-root.md) -14. [`PR-14-project-runtime-core-snapshot-model-and-lifecycle.md`](./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md) -15. [`PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md) -16. [`PR-16-write-lane-command-completion-and-used-write-services.md`](./PR-16-write-lane-command-completion-and-used-write-services.md) -17. [`PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md`](./PR-17-studio-runtime-adapter-and-assets-workspace-consumption.md) -18. [`PR-18-legacy-service-retirement-and-regression-hardening.md`](./PR-18-legacy-service-retirement-and-regression-hardening.md) -19. [`PR-19-api-surface-audit-model-separation-and-public-read-dtos.md`](./PR-19-api-surface-audit-model-separation-and-public-read-dtos.md) -20. [`PR-20-asset-action-capabilities-and-register-first-delivery.md`](./PR-20-asset-action-capabilities-and-register-first-delivery.md) -21. [`PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md) -22. [`PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md`](./PR-22-delete-asset-action-confirmation-and-fs-first-manifest-removal.md) -23. [`PR-23-move-asset-action-wizard-and-fs-first-relocation.md`](./PR-23-move-asset-action-wizard-and-fs-first-relocation.md) -24. [`PR-24-asset-file-cache-hydration-and-walker-reuse.md`](./PR-24-asset-file-cache-hydration-and-walker-reuse.md) -25. [`PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md) -26. [`PR-26-walker-cache-input-and-comparison-policy.md`](./PR-26-walker-cache-input-and-comparison-policy.md) -27. [`PR-27-runtime-walkresult-and-cache-integration.md`](./PR-27-runtime-walkresult-and-cache-integration.md) -28. [`PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md) -29. [`PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md) -30. [`PR-30-pack-wizard-summary-snapshot-query.md`](./PR-30-pack-wizard-summary-snapshot-query.md) -31. [`PR-31-pack-wizard-validation-snapshot-gate.md`](./PR-31-pack-wizard-validation-snapshot-gate.md) -32. [`PR-32-palette-declarations-with-explicit-index-contract.md`](./PR-32-palette-declarations-with-explicit-index-contract.md) -33. [`PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md`](./PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md) -34. [`PR-34-tile-bank-diagnostics-and-validation-hardening.md`](./PR-34-tile-bank-diagnostics-and-validation-hardening.md) -35. [`PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md`](./PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md) -36. [`PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md`](./PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md) - -Current wave discipline from `PR-11` onward: - -- cleanup and active-surface reduction happen before runtime implementation; -- the wave is service-first and Studio-driven; -- `doctor`, `build/pack`, and background reconcile are explicitly deferred; -- code that is not used by the active service wave should be removed instead of preserved speculatively. - -Recommended dependency chain: - -`PR-01 -> PR-02 -> PR-03 -> PR-04 -> PR-05 -> PR-06 -> PR-07 -> PR-08 -> PR-09 -> PR-10 -> PR-11 -> PR-12 -> PR-13 -> PR-14 -> PR-15 -> PR-16 -> PR-17 -> PR-18 -> PR-19 -> PR-20 -> PR-21 -> PR-22 -> PR-23 -> PR-24 -> PR-25 -> PR-26 -> PR-27 -> PR-28 -> PR-29 -> PR-30 -> PR-31 -> PR-32 -> PR-33 -> PR-34 -> PR-35 -> PR-36` +When a new execution wave starts, add only the PRs that still represent pending work. +Do not repopulate this directory with already-absorbed historical implementation slices. diff --git a/docs/studio/README.md b/docs/studio/README.md index 2fd70a41..604f5e66 100644 --- a/docs/studio/README.md +++ b/docs/studio/README.md @@ -104,10 +104,15 @@ The preferred Studio documentation flow is: - `agendas/` stores currently open Studio questions. - `decisions/` stores only decisions that still need propagation. -- `pull-requests/` stores execution plans. +- `pull-requests/` stores only execution plans for pending work. - `specs/` stores the normative Studio contract. - `learn/` stores teaching-oriented Studio knowledge. -The current Studio core and first `Assets` workspace wave have already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles. +The current Studio core and first `Assets` workspace wave have already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). +At this moment: + +- `agendas/` retains only topics that are still open; +- `decisions/` is empty because the last accepted wave was fully propagated; +- `pull-requests/` is empty because the historical execution wave was absorbed into `learn/`. If implementation exposes a missing UI or interaction decision, stop and return to `agendas/` or `decisions/`. diff --git a/docs/studio/agendas/Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md b/docs/studio/agendas/Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md deleted file mode 100644 index 0a5b7860..00000000 --- a/docs/studio/agendas/Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md +++ /dev/null @@ -1,80 +0,0 @@ -# Asset Bank Composition Snapshot Transfer to Details DTOs Agenda - -Status: Open -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Problem - -The `Bank Composition` section needs a stable details-facing data shape before any component or middleware work can proceed. - -Today the underlying information comes from two different sources: - -- snapshot state derived from `walkResult`, which should feed `available` files; -- `asset.json`, which should feed the currently `selected` files for build composition. - -This agenda exists to close how those sources should be transferred into Studio-facing DTOs for `Asset Details`. - -## Context - -Recent packer/runtime work already gives the Studio enough source information to populate a first-wave `Bank Composition` section: - -- registered assets have stable identity; -- the snapshot already contains file inventory derived from `walkResult`; -- blocking diagnostics already exclude files from being generally available; -- selection state is persisted in `asset.json` and is expected to move through the newer `artifacts` shape. - -The Studio should not bind raw UI code directly to packer internals. -The section needs a dedicated Studio DTO layer. - -## Options - -1. Bind the UI directly to snapshot and manifest shapes. -2. Build one dedicated Studio bank-file DTO for both `available` and `selected` rows. -3. Build separate DTOs for `available` rows and `selected` rows. - -## Tradeoffs - -1. Direct binding is fast initially but couples Studio too tightly to packer/runtime structures. -2. One shared DTO keeps the section simpler and is easier to use across transfer list, meter, and staged draft state. -3. Separate DTOs may model source differences more explicitly, but they add mapping and coordination overhead early. - -## Recommendation - -Adopt one dedicated Studio DTO family for bank composition rows and section state. - -Baseline direction: - -- `walkResult`-derived snapshot rows become `available`; -- `asset.json` composition state becomes `selected`; -- both are projected into Studio-owned DTOs before reaching the section UI; -- the DTO should be generic enough to work for any bank type, even if family-specific fields arrive later. -- the DTO field set should stay intentionally small and grow only when a concrete UI need appears. - -### First-Wave DTO Baseline - -The first-wave DTO direction is intentionally pragmatic: - -- define one Studio-owned bank-file DTO family for both `available` and `selected` rows; -- add fields incrementally as real section behavior requires them; -- do not project blocking files into the UI DTO layer at all; -- keep selected-file order visual in the UI, but persist it in `asset.json` through an explicit index shape such as `{ file, index }`. -- start with this minimum first-wave field set: - `fileId/path`, `displayName`, `size`, `lastModified`, `fingerprint`, and `metadata`. - -## Open Questions - -No open questions remain in this agenda wave. - -### Resolved In This Agenda Wave - -The following points are now closed: - -1. The DTO field set should start small and grow only as concrete UI needs appear. -2. Only non-blocking files become `available` DTOs; blocking files should not be projected into the section DTO layer. -3. UI ordering is visual, while persisted ordering in `asset.json` should use an explicit index representation such as `{ file, index }`. -4. The first DTO revision should start with `fileId/path`, `displayName`, `size`, `lastModified`, `fingerprint`, and `metadata`. - -## Next Suggested Step - -Turn this into a `decision` that closes the first-wave Studio DTO shape for `Bank Composition` details data. diff --git a/docs/studio/agendas/Agenda-02-Asset-Bank-Composition-Base-Components.md b/docs/studio/agendas/Agenda-02-Asset-Bank-Composition-Base-Components.md deleted file mode 100644 index 24be7c30..00000000 --- a/docs/studio/agendas/Agenda-02-Asset-Bank-Composition-Base-Components.md +++ /dev/null @@ -1,87 +0,0 @@ -# Asset Bank Composition Base Components Agenda - -Status: Open -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Problem - -The `Bank Composition` section depends on two new Studio components: - -- `StudioDualListView` -- `StudioAssetCapacityMeter` - -Those components need a first-wave contract and scope before the section shell or middleware can be implemented safely. - -## Context - -The current direction is already partially fixed: - -- `StudioDualListView` should be abstract; -- the first concrete subclass should be asset-details-specific; -- right-list ordering must support `move up`, `move down`, and visible indices; -- `StudioAssetCapacityMeter` should be a vertical, game-like progress bar with color bands and percentage text; -- both components should stay intentionally dumb and leave family-specific rules to middleware/controller logic. - -## Options - -1. Build highly generic reusable components from the start. -2. Build bank-composition-scoped Studio components with narrow first-wave APIs. -3. Skip dedicated components and build the section directly inside `AssetDetails`. - -## Tradeoffs - -1. Highly generic components risk overengineering before the first section is proven. -2. Narrow first-wave components keep momentum and preserve room to generalize later from real usage. -3. Inline section code would move faster once, but it would bury behavior that already deserves named UI building blocks. - -## Recommendation - -Build dedicated first-wave components with narrow APIs: - -- abstract `StudioDualListView` as the transfer-list base; -- one asset-details concrete subclass first; -- `StudioAssetCapacityMeter` as a dumb vertical meter component with color thresholds and percentage display. - -Do not force broad reuse rules yet. - -### First-Wave Component Baseline - -The first-wave component contract should stay intentionally small. - -`StudioDualListView` should expose only the hooks needed for the initial bank-composition section: - -- row text and/or row graphic projection; -- current left and right collections; -- current selection state; -- move left-to-right; -- move right-to-left; -- `moveUp`; -- `moveDown`; -- visible index refresh for the right-side list. - -The first concrete asset-details subclass should render rows directly. -Do not introduce a separate row renderer abstraction yet. - -`StudioAssetCapacityMeter` should start as a dumb visual component with these baseline inputs: - -- `progress` in the `0..1` range; -- a label, including percentage text when needed; -- a severity band state; -- optional hint text. - -## Open Questions - -No open questions remain in this agenda wave. - -### Resolved In This Agenda Wave - -The following points are now closed: - -1. `StudioDualListView` should expose only a narrow first-wave hook set for row projection, selection, transfers, reordering, and right-list index refresh. -2. The first concrete asset-details subclass should own row rendering directly. -3. `StudioAssetCapacityMeter` should start with `progress`, label, severity band state, and optional hint text. - -## Next Suggested Step - -Turn this into a `decision` that fixes the first-wave component contracts for `StudioDualListView` and `StudioAssetCapacityMeter`. diff --git a/docs/studio/agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md b/docs/studio/agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md deleted file mode 100644 index 5a18291f..00000000 --- a/docs/studio/agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md +++ /dev/null @@ -1,77 +0,0 @@ -# Asset Bank Composition Section Shell Agenda - -Status: Open -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Problem - -`Bank Composition` needs a section shell inside `Asset Details` before behavior is added. - -That shell must align visually and operationally with existing sections, especially `Runtime Contract`, instead of inventing a separate layout and editing model. - -## Context - -The current baseline is already known: - -- `Bank Composition` is a `VBox` section like the others; -- it is always visible for the current bank-based families; -- it should follow the same staged-editing model as `Runtime Contract`; -- the section body should place the dual list on the left and the capacity meter on the right. - -This agenda focuses on the static shell and section composition, not the internal behavior. - -## Options - -1. Add the section only when behavior is ready. -2. Build the section shell first, with placeholder or disabled behavior. -3. Hide the section behind an experimental flag. - -## Tradeoffs - -1. Waiting for full behavior keeps the surface hidden longer and delays visual integration feedback. -2. A shell-first approach lets the Studio validate section rhythm, spacing, controls, and staged-edit affordances early. -3. A flag adds operational complexity without much value if the section is already part of the near-term plan. - -## Recommendation - -Create the `Bank Composition` section shell early, with no real behavior yet. - -Baseline expectations: - -- section header and actions align with `Runtime Contract`; -- `change`, `apply`, `reset`, and `cancel` are part of the shell contract; -- body layout already reserves the dual-list and meter regions; -- the shell may render with placeholder or disabled internals until middleware arrives. - -### First-Wave Shell Baseline - -The first-wave shell should mirror `Runtime Contract` as closely as practical at the JavaFX composition level. - -That includes: - -- the same section rhythm and action placement model; -- the same staged-edit shell expectations; -- alignment with the existing `FormSession` pattern instead of inventing a separate section lifecycle. - -Before middleware wiring is ready, the body should render in a disabled or read-only state rather than as an empty placeholder. - -Outside `change` mode, the section should show the current persisted state as read-only. -It should not stay visually neutral or look absent when data already exists. - -## Open Questions - -No open questions remain in this agenda wave. - -### Resolved In This Agenda Wave - -The following points are now closed: - -1. The section shell should mirror `Runtime Contract` as closely as practical at the JavaFX composition level. -2. The shell should align with the existing `FormSession` model for staged editing. -3. Before middleware is ready, the body should render disabled or read-only internals instead of an empty placeholder. -4. Outside `change` mode, the section should render the current persisted state as read-only. - -## Next Suggested Step - -Turn this into a `decision` that fixes the shell contract and static layout of the `Bank Composition` section. diff --git a/docs/studio/agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md b/docs/studio/agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md deleted file mode 100644 index 8a3689ab..00000000 --- a/docs/studio/agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md +++ /dev/null @@ -1,92 +0,0 @@ -# Asset Bank Composition Middleware and Staged Editing Agenda - -Status: Open -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Problem - -`StudioDualListView` and `StudioAssetCapacityMeter` are intentionally dumb. -That means `Bank Composition` needs a middleware/controller layer that owns: - -- family-specific capacity rules; -- staged draft state; -- `change` / `apply` / `reset` / `cancel` orchestration; -- hard-limit decisions about whether a candidate file can enter the selected list. - -Without that layer, component responsibilities will blur quickly. - -## Context - -The current direction already rejects two extremes: - -- no component should hide bank-family rules internally; -- the first wave should not overgeneralize into a universal bank manager abstraction. - -The middleware/controller therefore needs to be explicit, scoped to `Asset Details`, and designed to evolve incrementally. - -## Options - -1. Put orchestration inside the section control itself. -2. Create a dedicated bank-composition middleware/controller for the section. -3. Push family-specific logic down into the transfer list and meter components. - -## Tradeoffs - -1. Section-local orchestration reduces file count initially, but risks turning `AssetDetails` into a heavy behavior host. -2. A dedicated middleware/controller keeps the section and components simpler while preserving room for bank-family policies. -3. Embedding rules into components breaks the current design goal of keeping them dumb and composable. - -## Recommendation - -Create a dedicated bank-composition middleware/controller for the section. - -Baseline expectations: - -- own the draft state while editing is active; -- translate persisted state into editable state on `change`; -- support `reset` back to the persisted state; -- support `cancel` by discarding draft changes; -- keep `apply` stubbed or disabled until persistence is wired; -- delegate family-specific capacity logic through narrowly scoped policies instead of premature platform-wide abstractions. - -### First-Wave Middleware Baseline - -The first wave should not introduce a second session model parallel to the one already used by Studio. - -The middleware/controller should be built around `StudioFormSession` as the common staged-edit core. - -Family-specific variation should not come from subclassing `StudioFormSession`. -It should come from family-specific draft factories and policies that operate on a shared session model. - -Baseline direction: - -- `StudioFormSession` owns `source`, `draft`, `mode`, `isDirty`, `beginEdit`, `reset`, `cancel`, and `apply`; -- the bank-composition middleware/controller coordinates that form session for the section; -- each asset family can offer its own draft-construction and bank-composition policy implementation; -- those policies should decide transfer eligibility, reorder effects, capacity usage, and hard-limit blockers; -- `apply` may remain stubbed or disabled until persistence is wired, but the session contract should already be complete. - -The minimal state published by the middleware/controller should be one section-facing view model carrying: - -- shell state such as `isEditing`, `isDirty`, and action availability; -- left and right list state; -- capacity-meter state; -- active blockers and hint messages when relevant. - -## Open Questions - -No open questions remain in this agenda wave. - -### Resolved In This Agenda Wave - -The following points are now closed: - -1. The middleware/controller should be built around `StudioFormSession`, not a parallel staged-edit model. -2. Family-specific behavior should come from draft factories and policies, not from subclassing `StudioFormSession`. -3. Family-specific rules should be represented first as small policies offered per asset family. -4. The middleware/controller should publish one section-facing view model with shell state, list state, meter state, blockers, and hints. - -## Next Suggested Step - -Turn this into a `decision` that fixes the middleware/controller contract and staged-edit lifecycle for the first wave. diff --git a/docs/studio/agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md b/docs/studio/agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md deleted file mode 100644 index 19170571..00000000 --- a/docs/studio/agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md +++ /dev/null @@ -1,94 +0,0 @@ -# Asset Bank Composition WorkspaceBus Interaction Agenda - -Status: Open -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Problem - -The `Bank Composition` section should use `workspaceBus` for coordination, but the first-wave event contract should stay small and be designed together with the middleware/controller. - -This agenda exists to close the first minimal event surface without inventing an oversized bus protocol too early. - -## Context - -The current baseline is already known: - -- events and middleware should evolve together; -- the first event baseline can stay very small; -- capacity changes are naturally expressed as percentage deltas or level changes in the `0..1` range; -- the transfer list and meter should be consumers of orchestrated state, not independent sources of product rules. - -## Options - -1. Define a broad event taxonomy upfront. -2. Define only the minimum events needed for the first staged-edit interaction loop. -3. Avoid `workspaceBus` and wire components directly. - -## Tradeoffs - -1. A broad taxonomy is easy to regret and hard to prune once code lands. -2. A minimal contract matches the current incremental direction and keeps future changes cheap. -3. Direct wiring would fight the current workspace architecture and reduce observability of section state changes. - -## Recommendation - -Define a minimal first-wave `workspaceBus` contract together with the middleware/controller. - -Baseline direction: - -- begin with the smallest useful set of section-local events; -- include capacity increase/decrease semantics in the `0..1` range only as needed; -- avoid encoding family-specific product rules directly into bus event types. - -### First-Wave Event Baseline - -The first wave should keep user actions local to the middleware/controller whenever possible. - -That means the following actions do not need to become public `workspaceBus` commands in the first implementation: - -- `beginEdit` -- `moveToSelected` -- `moveToAvailable` -- `moveUp` -- `moveDown` -- `reset` -- `cancel` -- `apply` - -The middleware/controller should receive those actions locally, recalculate section state, and publish only the state transitions or lifecycle notifications that matter outside the section. - -The first public `workspaceBus` notifications should stay minimal: - -- `BankCompositionDraftChanged` -- `BankCompositionCapacityChanged` -- `BankCompositionApplyRequested` -- `BankCompositionApplied` -- `BankCompositionApplyFailed` - -Capacity notifications should use absolute progress in the `0..1` range rather than deltas. - -A practical first-wave shape for capacity notifications is: - -- `progress` -- `severity` -- `blocked` - -If internal increase/decrease semantics are useful later, they can remain local implementation detail rather than part of the initial public bus contract. - -## Open Questions - -No open questions remain in this agenda wave. - -### Resolved In This Agenda Wave - -The following points are now closed: - -1. First-wave user actions should stay local to the middleware/controller rather than becoming public bus commands. -2. The first public `workspaceBus` contract should be notification-oriented. -3. Capacity notifications should use absolute `0..1` progress rather than deltas. -4. A minimal first-wave bus surface is enough: draft change, capacity change, apply requested, apply success, and apply failure. - -## Next Suggested Step - -Turn this into a `decision` that fixes the minimal first-wave `workspaceBus` contract for `Bank Composition`. diff --git a/docs/studio/agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md b/docs/studio/agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md deleted file mode 100644 index d195555c..00000000 --- a/docs/studio/agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md +++ /dev/null @@ -1,98 +0,0 @@ -# Asset Bank Composition Persistence and Snapshot Propagation Agenda - -Status: Open -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Problem - -When the developer clicks `apply`, the selected files for bank composition must be persisted and reflected back into runtime state. - -That write path spans Studio and packer concerns: - -- staged selected files must be serialized into `asset.json`; -- the older `inputsByRole` shape should give way to the newer `artifacts` shape; -- the minimal runtime snapshot must reflect the persisted result after apply. - -## Context - -The earlier agendas in this sequence assume `apply` may remain disabled or stubbed until persistence is ready. -This agenda isolates the write-path discussion so the rest of the UI can progress first. - -The current direction is already mostly known: - -- persistence should happen through packer, not by having Studio write manifest files directly; -- selected composition should be stored in `asset.json`; -- runtime state should be refreshed after persistence so `Asset Details` stays coherent. - -## Options - -1. Let Studio write `asset.json` directly. -2. Route `apply` through packer services and let packer own manifest persistence plus snapshot refresh. -3. Persist only to runtime state first and defer manifest persistence. - -## Tradeoffs - -1. Direct manifest writes from Studio would bypass packer ownership and create duplicate write rules. -2. A packer-owned write path is cleaner and aligns with existing asset mutation flows. -3. Runtime-only persistence would create an unstable editing model and almost certainly drift from disk state. - -## Recommendation - -Route `apply` through packer and persist selected files into `asset.json` using the newer `artifacts` representation. - -Baseline expectations: - -- `apply` submits the selected ordered files to packer; -- packer updates `asset.json`; -- packer propagates the resulting minimal state back into the runtime snapshot; -- Studio refreshes the section from the updated details/snapshot state instead of trusting stale draft data. - -### Persistence Baseline - -The first-wave persistence direction is: - -- `artifacts` replaces the older `inputsByRole` representation in `asset.json`; -- the bank-composition selection should therefore persist through `artifacts`, not through a parallel legacy shape; -- selected file order should remain explicit in persisted data rather than relying on array position alone. - -### Apply Refresh and Failure Baseline - -After `apply`, the Studio should not trust stale draft state. - -The first-wave refresh baseline is: - -- packer persists the selected ordered files into `asset.json`; -- packer refreshes the minimal runtime snapshot state needed by `Asset Details`; -- the Studio rebinds the section from the refreshed persisted state and returns the section to consistent read-only mode. - -The minimum refreshed state should include: - -- persisted `selected` rows; -- the current `available` projection for details; -- recalculated capacity state; -- recalculated blockers or eligibility state relevant to the section. - -If `apply` fails: - -- the draft must not be discarded; -- the section must remain in editing mode; -- the middleware/controller should publish `BankCompositionApplyFailed`; -- the UI should show a local error or hint surface; -- the user should still be able to retry, reset, or cancel. - -## Open Questions - -No open questions remain in this agenda wave. - -### Resolved In This Agenda Wave - -The following points are now closed: - -1. `artifacts` should replace the older `inputsByRole` shape rather than coexist with it for bank-composition persistence. -2. After `apply`, packer should refresh the minimal snapshot state required by `Asset Details` and Studio should rebind from that refreshed persisted state. -3. If `apply` fails, the draft remains intact, the section stays in editing mode, and the UI surfaces a local failure state while preserving retry, reset, and cancel. - -## Next Suggested Step - -Turn this into a cross-domain `decision` or a paired `docs/studio` + `docs/packer` decision set that closes the apply write path. diff --git a/docs/studio/agendas/Asset Bank Composition Area - Dual List and Capacity Meter Agenda.md b/docs/studio/agendas/Asset Bank Composition Area - Dual List and Capacity Meter Agenda.md deleted file mode 100644 index 57ba1f24..00000000 --- a/docs/studio/agendas/Asset Bank Composition Area - Dual List and Capacity Meter Agenda.md +++ /dev/null @@ -1,234 +0,0 @@ -# Asset Bank Composition Area - Dual List and Capacity Meter Agenda - -Status: Open (Umbrella, split into follow-up agendas) -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Problem - -The Studio `Assets` details area does not yet expose an explicit authoring surface for bank composition based on internal asset files. - -The next planned area is not a simple form row. -It combines: - -- a left-side transfer area with `available files` and `files included in build`; -- a right-side vertical capacity meter for fixed bank size usage; -- rule-driven gating where files can no longer be moved into the build set once the bank reaches its fixed size limit. - -This looks small in layout terms, but it hides many interaction details: - -- which files are shown at all; -- which files are build-eligible; -- how diagnostics affect transfer availability; -- whether order matters; -- how the meter behaves near or above the limit; -- and how Studio should explain hard capacity blockers without becoming noisy. - -This topic needs a Studio agenda before it becomes a decision or implementation PR. - -## Context - -Recent packer work now gives the runtime snapshot enough information to support this UI discussion more concretely: - -- available files per registered asset; -- build-candidate files derived from the current walk; -- file-scoped diagnostics kept segregated for future UI use; -- measured bank size usage for the current build-candidate set; -- stable asset identity through `asset_id` for registered assets only. - -That means the Studio can now discuss this area against a real backend shape instead of inventing a purely visual placeholder. - -Important constraints already known: - -1. only registered assets should participate in this internal bank-composition flow; -2. the snapshot should retain file inventory and build-candidate information, but not raw file bytes; -3. bank size is fixed on the hardware/runtime side; -4. when the bank reaches its maximum size, the UI must block adding more files into the build set. - -## Current Code Context - -The current Studio selected-asset details composition is still centered on: - -- summary and actions; -- runtime contract; -- diagnostics and preview-related surfaces already present in the details flow. - -Relevant code anchors today: - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java` -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/contract/AssetDetailsContractControl.java` -- `docs/studio/specs/4. Assets Workspace Specification.md` - -There is no existing `DualListView` or dedicated bank-composition control in `prometeu-studio` yet. - -That matters because this agenda is not only about layout. -It is about how a new section inside `Asset Details` should behave and how its internal components should coordinate. - -## Recommendation - -Create a dedicated `Bank Composition` section inside `Asset Details`, implemented as a `VBox` section just like the other asset-details sections, and explicitly backed by packer runtime data. - -Operationally, this section should follow the same staged-editing pattern already used by `Runtime Contract`, including `change`, `apply`, `reset`, and `cancel` actions. - -Recommended baseline shape: - -1. left side of the section body: a dedicated `StudioDualListView` component with: - - left list = available files - - right list = files included in build -2. right side of the section body: a dedicated vertical `StudioAssetCapacityMeter` component showing current measured usage versus fixed bank capacity -3. hard gating rule: - if adding a file would exceed the fixed bank size, the move must be blocked before the item enters the build list -4. coordination rule: - the transfer list and the capacity meter must be built as components for this asset-workspace use case and must be able to exchange typed events through the `workspaceBus` - -Why this direction: - -- it gives bank composition its own didactic and operational area inside `Asset Details`; -- it leaves room to discuss many smaller details without destabilizing the rest of selected-asset details; -- it keeps authoring behavior aligned with the existing `Runtime Contract` section instead of inventing a second editing model inside `Asset Details`; -- it aligns with the Studio event-driven workspace model already used by the `Assets` workspace. - -### Component Direction - -The first implementation should not treat these controls as isolated local widgets. - -Rules: - -- `StudioDualListView` is the component name for the transfer-list surface of this section; -- `StudioDualListView` should be introduced as an abstract Studio component created for this bank-composition section; -- `StudioDualListView` should leave concrete behavior to subclasses, with capabilities added incrementally as real bank-composition needs appear; -- `StudioAssetCapacityMeter` is the component name for the vertical capacity meter of this section; -- `StudioAssetCapacityMeter` should also be introduced as a Studio component created for this bank-composition section; -- both components must be able to publish and consume typed events through the `workspaceBus`; -- the event model must allow coordination not only between the transfer list and the capacity meter, but also with surrounding details/workspace components when selection, eligibility, diagnostics, or staged apply behavior evolves; -- the first event baseline should stay intentionally small: - increase and decrease capacity updates expressed as percentage in the `0..1` range are enough to start; -- the initial component scope is still bank-composition-specific, even if later refactoring makes them reusable elsewhere. - -### Current Baseline Assumptions - -The following points are now assumed for the current discussion wave: - -1. `StudioDualListView` is abstract, with concrete subclasses supplying bank-specific behavior over time. -2. `Bank Composition` is always visible for the current asset families, because the currently active bank-based families are `Tile` and `Sound`. -3. `available files` come directly from the snapshot projection derived from `walkResult`. -4. only files without blocking diagnostics may appear in `available files`. -5. file order in the right list affects build output and must be developer-controlled. -6. the right list therefore needs ordering support and should surface indices as part of the UI. -7. capacity computation is family-specific and must not be normalized prematurely into one fake universal formula. -8. the bank-composition section should receive its data as part of the normal asset-details fetch. -9. `StudioDualListView` and `StudioAssetCapacityMeter` should both remain intentionally dumb; a bank-composition middleware/controller should own family-specific UI rules and hard-limit orchestration. -10. if the Studio later needs non-bank-based asset handling, that should be introduced via another bank manager/composition manager rather than by overengineering this first wave. -11. the section should use the same staged interaction model as `Runtime Contract`, with `change`, `apply`, `reset`, and `cancel`. - -### Family-Specific Capacity Notes - -The current bank-capacity semantics already differ by family: - -- `Tile` banks are matrix-based. - Example: - a `256x256` indexed matrix with tiles configured as `32x32` yields `8x8 = 64` tile slots. - If each selected build file contributes one `32x32` tile, the bank can contain at most `64` selected files. -- `Sound` banks are byte-budget-based. - The relevant measure is sample size in bytes, with a fixed bank capacity such as `1 MB`. - -That means `StudioAssetCapacityMeter` must be driven by bank-family semantics rather than by one simplistic shared percentage algorithm hidden from the user. - -### Meter Behavior Baseline - -The current direction for the meter is explicitly game-like: - -- a vertical progress-bar style meter that rises as the bank fills; -- green, orange, and red severity bands instead of one neutral fill; -- a percentage label below the bar; -- supporting text or hint copy explaining that banks have fixed capacity and must not be exceeded; -- hint text should also nudge the developer toward splitting or reorganizing the asset when the bank is too full. - -Initial thresholds: - -- green below `65%` -- orange at `>= 65%` or `> 9/16` -- red at `>= 95%` or `> 14/16` - -Hard-limit interaction baseline: - -- the UI should disable only moves from left to right when capacity is exhausted or the candidate item would overflow the bank; -- moving items from right to left must remain possible; -- ordering actions on the right list must remain possible; -- the surface should still explain why add is blocked, instead of silently failing. - -### Section Workflow Baseline - -`Bank Composition` should not auto-persist edits while the developer is moving files around. - -The first-wave workflow should mirror `Runtime Contract`: - -- `change` enters editable mode; -- list transfers, ordering, and capacity feedback happen inside the staged draft state; -- `apply` persists the new composition; -- `reset` returns the draft to the last persisted state while staying in the editing flow; -- `cancel` exits editing and discards uncommitted draft changes. - -This keeps the mental model of `Asset Details` consistent across sections and avoids mixing immediate-write behavior with staged authoring behavior in the same surface. - -### Ordering Baseline - -The current first-wave baseline for right-list ordering is: - -- `move up` -- `move down` -- visible indices on the right/build list - -Drag-and-drop may still be attractive later, but it is not yet required to validate the first wave. - -## Open Questions - -1. What exact first-wave event and controller contract should be defined together for the bank-composition flow, since the `workspaceBus` events and the bank-composition middleware/controller should evolve as one design surface? -2. What exact explanatory text should the section show for tile-bank exhaustion versus sound-bank exhaustion so the user understands the capacity rule, not just the percentage? - -### Resolved In This Agenda Wave - -The following points are now closed for the first wave: - -1. The UI-facing file-row structure should be a dedicated Studio DTO for any bank type. -2. The first concrete `StudioDualListView` subclass should be asset-details-specific. -3. The event contract and middleware/controller shape should be designed together incrementally, without premature generalization. -4. Detailed wording for family-specific explanatory copy can be deferred until the section contract is otherwise ready. - -## Suggested Next Step - -Do not implement the area yet. - -This umbrella agenda is now intentionally split into focused follow-up agendas aligned to the proposed execution order: - -1. snapshot transfer into details DTOs: - [`Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md`](./Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md) -2. base component construction: - [`Agenda-02-Asset-Bank-Composition-Base-Components.md`](./Agenda-02-Asset-Bank-Composition-Base-Components.md) -3. `Bank Composition` section shell: - [`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](./Agenda-03-Asset-Bank-Composition-Section-Shell.md) -4. bank-composition middleware/controller: - [`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](./Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md) -5. middleware-driven interaction: - [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](./Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md) -6. persistence: - [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](./Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md) - -### Proposed Execution Order - -The current proposed implementation order is: - -1. transfer snapshot state into asset-details DTOs -2. build the base and concrete UI components -3. create the `Bank Composition` UI shell with no behavior -4. introduce the bank-composition middleware/controller and staged DTO flow -5. wire developer actions through middleware and `workspaceBus` -6. persist the selected composition back through packer into `asset.json` and the minimal snapshot - -This sequence is useful not only for implementation, but also for decision slicing: - -- early decisions can close DTO and section-shape questions first; -- middle decisions can close middleware and event-orchestration questions; -- the final decision can close persistence into `asset.json` and minimal snapshot propagation. - -The next correct step is to work these follow-up agendas in order and derive smaller `decision` records from them instead of trying to close the whole bank-composition architecture in one pass. diff --git a/docs/studio/agendas/Pack Wizard in Assets Workspace Agenda.md b/docs/studio/agendas/Pack Wizard in Assets Workspace Agenda.md deleted file mode 100644 index 20e37df2..00000000 --- a/docs/studio/agendas/Pack Wizard in Assets Workspace Agenda.md +++ /dev/null @@ -1,282 +0,0 @@ -# Pack Wizard in Assets Workspace Agenda - -Status: Open -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Problem - -O workspace `Assets` já reserva a action area para `Pack`, mas ainda não existe uma discussão fechada sobre o fluxo exato desse comando no Studio. - -O pedido atual não é apenas adicionar um botão. -O `Pack` precisa abrir um modal que funcione como wizard operacional do empacotador e deixe claro: - -- o resumo do que será empacotado; -- a validação obrigatória antes do build; -- a regra de bloqueio quando existirem diagnostics em assets incluídos; -- o progresso da geração do artefato; -- e o resumo final do resultado. - -Sem essa agenda, há risco de misturar decisão de UX com semântica de packer e de implementar um modal visualmente correto, mas operacionalmente fraco. - -## Context - -O estado atual já sugere várias restrições importantes: - -1. o `Assets` workspace define `Pack` como ação global de workspace, não como ação do asset selecionado; -2. a spec do Studio já separa `Pack` do fluxo de staged mutations sensíveis; -3. a spec do packer define `assets.pa` como artefato runtime autoritativo, com `asset_table` determinística e baseada apenas nos assets incluídos no build set atual; -4. o packer já trata diagnostics como parte do modelo operacional, então o Studio não deve inventar uma semântica paralela de validação; -5. o usuário precisa de feedback de progresso e de falha com drill-down por asset, não apenas logs. - -Boundary baseline desta agenda: - -- o Studio é casca operacional; -- o Studio chama serviços do packer, observa progresso e apresenta estado; -- o trabalho bruto de summary, validation, packing e result pertence ao packer; -- o Studio não deve reimplementar regras de build, gating ou ordenação. - -Artefatos e referências já relevantes: - -- `docs/studio/specs/4. Assets Workspace Specification.md` -- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md` -- `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md` -- `docs/packer/pull-requests/PR-08-assets-pa-and-companion-artifact-emission.md` - -Nota de nomenclatura: - -- a spec vigente usa `assets.pa` como nome canônico do artefato; -- esta agenda deve seguir `assets.pa`, mesmo que a conversa operacional use `asset.pa` informalmente. - -## Current Code Context - -O contexto atual no código Studio é suficiente para ancorar a discussão: - -- o botão `Pack` foi introduzido na action bar do workspace em `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`; -- o workspace já possui região inline de progresso, painel de logs e integração com eventos do packer; -- ainda não existe wizard de pack nem API explícita de `pack` em `PackerWorkspaceService`. - -Isso significa que o fluxo precisa ser decidido primeiro e depois propagado para: - -- contrato da API do packer; -- eventos operacionais de progresso; -- modelagem de resultado; -- e shell/modal do Studio. - -Leitura operacional explícita: - -- o wizard é Studio-owned apenas como shell de interação; -- a semântica do pack é packer-owned ponta a ponta. - -## Options - -### Option A - Single modal with one primary action - -Abrir um modal com resumo inicial e um único botão `Pack`. -Ao confirmar, o Studio valida, empacota e mostra sucesso ou falha no mesmo corpo, sem etapas explícitas de wizard. - -### Option B - Multi-step wizard with explicit operational phases - -Abrir um wizard com fases claras: - -1. `Summary` -2. `Validation` -3. `Packing` -4. `Result` - -Cada fase deixa explícito o estado operacional atual e evita que o usuário perca contexto entre bloqueio, execução e resultado. - -### Option C - Split flow with preflight modal plus separate progress dialog - -Abrir um modal curto para resumo e validação. -Se tudo passar, fechar esse modal e abrir outro diálogo dedicado só ao progresso e resultado do pack. - -## Tradeoffs - -- Option A é mais rápida de implementar, mas colapsa estados diferentes demais em uma única superfície e tende a virar um modal ambíguo. -- Option A também dificulta explicar por que o pack foi bloqueado e o que exatamente falhou por asset. -- Option B exige mais estrutura de estado, mas deixa o fluxo didático, previsível e alinhado ao pedido de wizard empacotador. -- Option B também facilita mapear cada fase para contratos distintos do packer: preflight, validação, execução e resultado. -- Option C separa bem responsabilidades visuais, mas fragmenta a experiência e pode parecer que o usuário saiu de um fluxo para entrar em outro. -- Option C ainda aumenta o custo de coordenação de foco, fechamento e recuperação de erro. - -## Recommendation - -Adotar `Option B` como baseline. - -O `Pack` deve abrir um wizard modal de workspace. -O Studio é owner apenas da apresentação e navegação do modal. -O packer é owner da semântica operacional, da validação, da execução e do resultado. - -### Recommended Flow - -#### 1. Summary - -O wizard abre em um resumo do build atual. -Esse resumo deve mostrar pelo menos: - -- quantidade de assets registrados e incluídos no build atual; -- quantidade de assets excluídos ou fora do build set; -- indicação de que o output canônico será `assets.pa`; -- indicação de que a `asset_table` seguirá a ordem determinística por `asset_id`, conforme spec; -- artefatos companion previstos quando aplicável. - -Regras: - -- assets não incluídos no build não entram no pack; -- assets não registrados também não entram no pack; -- o resumo deve deixar explícito que a operação trabalha sobre o build set atual, não sobre todo o workspace. -- o Studio apenas apresenta esse resumo; ele não recompõe localmente o build set. - -#### 2. Validation - -A segunda fase deve executar uma validação explícita sobre os assets incluídos no build. - -Baseline recomendado: - -- qualquer diagnostic bloqueante em asset incluído falha a validação e impede o início do pack; -- a validação deve ser tratada como processo packer-owned semelhante a um `deep sync` dry-run, mas restrito ao conjunto `registered + included in build`; -- a tela deve mostrar resumo agregado e amostragem por asset do que falhou; -- a UI deve permitir drill-down por asset sem despejar log cru como explicação principal; -- se houver warnings não bloqueantes, eles podem ser exibidos, mas não devem impedir o `Pack`. - -Modelo didático mínimo da tela: - -- topo com contagem de assets validados, aprovados e bloqueados; -- lista por asset com status; -- ao selecionar ou expandir um asset, mostrar diagnostics relevantes daquele asset. - -Baseline fechado nesta agenda wave: - -- a fase de validação mostra diagnostics bloqueantes por padrão; -- a tela deve permitir que o developer inspecione contexto adicional quando necessário; -- esse drill-down adicional não muda o foco principal da fase, que é explicar o gate de bloqueio. - -A responsabilidade pela classificação do que bloqueia ou não deve permanecer no packer. -O Studio apenas consome e apresenta essa classificação. - -Direção mais precisa para esta agenda: - -- a validação não é uma checagem local do Studio; -- a validação é uma operação explícita do packer; -- ela reutiliza a lógica de reconciliação/inspeção profunda necessária para afirmar se o build set atual pode ser empacotado; -- mas seu escopo é apenas o conjunto de assets que realmente participariam do pack. - -#### 3. Packing - -Se a validação passar, o wizard entra em fase de execução. - -Essa fase deve ser não editável, operante e orientada a progresso. - -Regras: - -- mostrar barra de progresso com atualização contínua; -- mostrar texto curto da etapa atual; -- manter o usuário no mesmo modal até conclusão, falha ou cancelamento suportado por contrato; -- deixar explícito que o pack está montando `assets.pa` e a `asset_table` conforme as specs vigentes; -- logs detalhados podem existir em área secundária, mas não substituem o indicador principal de progresso. -- durante `Packing`, o wizard não deve expor affordances de edição ou revisão que façam a operação parecer reversível ou parcialmente configurável. - -Semântica recomendada: - -- o packer expõe eventos ou snapshots de progresso por operação; -- o Studio mapeia isso para uma barra de progresso e rótulos humanos; -- o wizard não deve inferir progresso a partir de timers artificiais. - -Baseline fechado para a primeira versão: - -- não há cancelamento durante `Packing`; -- o modal permanece em estado operante até conclusão ou falha; -- a UI não deve simular cancelamento sem suporte cooperativo real do packer. - -#### 4. Result - -Ao concluir, o wizard deve mostrar um resumo final do resultado. - -O resumo deve cobrir: - -- status final: sucesso parcial ou falha; -- quantidade de assets efetivamente empacotados; -- artefatos emitidos; -- duração da operação; -- falhas ou avisos finais, quando existirem. - -Se houver falha depois de a validação ter passado, a tela final deve diferenciar: - -- falha de validação; -- falha de execução/geração; -- e falha de persistência/emissão. - -Baseline fechado nesta agenda wave: - -- o resumo principal prioriza `assets.pa`, duração e total de assets empacotados; -- companion artifacts ficam em drill-down secundário; -- os diagnostics do resultado tendem a já existir nos assets e não precisam dominar a superfície principal. - -### Contract Direction - -Para a próxima onda de decisão, o contrato recomendado é separar pelo menos três responsabilidades no packer: - -1. `preflight summary` do build set atual; -2. `validation` do build set como dry-run packer-owned semelhante a `deep sync`, com bloqueios agregados por asset; -3. `pack execution` com progresso estruturado e resultado final. - -Baseline fechado nesta agenda wave: - -- `summary`, `validation` e `pack execution` são chamadas distintas; -- o Studio não deve iniciar `pack execution` para conseguir `summary` ou `validation`; -- a separação deve permanecer visível na API consumida pelo Studio. - -O Studio deve orquestrar essas fases no wizard, mas não redefinir: - -- quais assets entram no build set; -- o que conta como diagnostic bloqueante; -- a ordem da `asset_table`; -- ou o que exatamente compõe `assets.pa`. - -Em termos práticos: - -- o Studio chama; -- o packer decide; -- o Studio mostra. - -### UI Direction - -O wizard deve ser operacional, não um formulário tradicional. - -Direção recomendada: - -- stepper simples no topo ou lateral; -- corpo central com conteúdo da fase; -- ações de navegação controladas pelo estado operacional; -- `Next` bloqueado quando a validação falhar; -- `Pack` disponível apenas quando a fase de validação estiver limpa; -- `Close` ou `Done` só ao final, ou em estados seguros de abortar. - -### Resolved In This Agenda Wave - -Os seguintes pontos ficam fechados como baseline para a próxima `decision`: - -1. `summary`, `validation` e `pack execution` são chamadas distintas. -2. A validação mostra diagnostics bloqueantes por padrão e permite inspeção adicional para o developer. -3. A primeira versão não suporta cancelamento durante `Packing`. -4. Companion artifacts ficam em drill-down secundário no resultado final. -5. A primeira versão não exporta nem copia o resumo de falhas. -6. Pode existir um botão `dumb` na UI como lembrete explícito de feature futura, sem comportamento operacional no `v1`. - -## Suggested Next Step - -O próximo passo correto é converter esta agenda em uma `decision` owner de `docs/studio`, com propagação explícita para `docs/packer`. - -Essa decision deve fechar: - -1. o shape do wizard e suas fases; -2. o gate de validação baseado em diagnostics dos assets incluídos; -3. o contrato mínimo de API/eventos que o packer precisa expor para suportar o wizard; -4. a distinção entre falha de validação e falha de execução; -5. o vocabulário canônico do resultado final em torno de `assets.pa` e `asset_table`. - -Depois disso, o trabalho deve ser decomposto em pelo menos dois planos: - -1. um `PR/plan` em `docs/packer` para summary, validation, pack execution, progress e result contract; -2. um `PR/plan` em `docs/studio` para shell do wizard, fases, binding de progresso e tela de resultado. diff --git a/docs/studio/agendas/README.md b/docs/studio/agendas/README.md index b20e9422..114bbe38 100644 --- a/docs/studio/agendas/README.md +++ b/docs/studio/agendas/README.md @@ -5,15 +5,8 @@ This directory contains active Studio discussion agendas. Active agendas: - [`Palette Management in Studio Agenda.md`](./Palette%20Management%20in%20Studio%20Agenda.md) -- [`Asset Bank Composition Area - Dual List and Capacity Meter Agenda.md`](./Asset%20Bank%20Composition%20Area%20-%20Dual%20List%20and%20Capacity%20Meter%20Agenda.md) -- [`Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md`](./Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md) -- [`Agenda-02-Asset-Bank-Composition-Base-Components.md`](./Agenda-02-Asset-Bank-Composition-Base-Components.md) -- [`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](./Agenda-03-Asset-Bank-Composition-Section-Shell.md) -- [`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](./Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md) -- [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](./Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md) -- [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](./Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md) -The shell, UI foundations, components admission baselines, and the first asset workspace wave were already consolidated into [`../specs/`](../specs/) and [`../learn/`](../learn/). +Closed Studio agenda waves must be absorbed into [`../specs/`](../specs/) and [`../learn/`](../learn/) instead of remaining here as historical residue. ## Purpose diff --git a/docs/studio/decisions/Bank Composition Base Components Decision.md b/docs/studio/decisions/Bank Composition Base Components Decision.md deleted file mode 100644 index 1791f4ae..00000000 --- a/docs/studio/decisions/Bank Composition Base Components Decision.md +++ /dev/null @@ -1,110 +0,0 @@ -# Bank Composition Base Components Decision - -Status: Decided -Cycle: 2026-03 -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Context - -The `Bank Composition` section inside `Asset Details` depends on two new Studio components: - -- `StudioDualListView` -- `StudioAssetCapacityMeter` - -These components need a first-wave contract before the section shell, middleware, and persistence work can proceed safely. - -The DTO projection boundary was already closed in: - -- [`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md) - -This decision closes the first-wave component direction discussed in: - -- [`Agenda-02-Asset-Bank-Composition-Base-Components.md`](../agendas/Agenda-02-Asset-Bank-Composition-Base-Components.md) - -## Decision - -Adopt narrow, bank-composition-scoped first-wave components. - -The component choices are: - -1. `StudioDualListView` remains an abstract Studio component; -2. the first concrete implementation is asset-details-specific; -3. `StudioAssetCapacityMeter` is a dumb visual component for vertical capacity display; -4. neither component should own bank-family product rules. - -`StudioDualListView` should expose only the hooks needed by the first `Bank Composition` wave: - -- row text and/or row graphic projection; -- current left and right collections; -- current selection state; -- move left-to-right; -- move right-to-left; -- `moveUp`; -- `moveDown`; -- visible right-list index refresh. - -The first asset-details concrete subclass should render rows directly. -Do not introduce a separate row-renderer abstraction in this first wave. - -`StudioAssetCapacityMeter` starts with these baseline inputs: - -- `progress` in the `0..1` range; -- a label, including percentage text when needed; -- a severity-band state; -- optional hint text. - -## Justification - -This keeps component scope small and aligned with the current implementation plan. - -The decision avoids two common mistakes: - -- overengineering highly generic components before the first section exists; -- burying section behavior directly inside `Asset Details` with no named component boundary. - -Direct row rendering in the first concrete dual-list implementation is the pragmatic choice. -There is no current evidence that a standalone row-renderer abstraction is needed. - -Keeping `StudioAssetCapacityMeter` dumb also protects the future middleware/controller boundary. -Family-specific rules should not leak into the visual component. - -## Invariants and Constraints - -The following constraints now apply: - -1. `StudioDualListView` must remain abstract in the first wave; -2. the first concrete `StudioDualListView` implementation belongs to the asset-details flow; -3. right-list ordering support must include `moveUp`, `moveDown`, and visible indices; -4. `StudioAssetCapacityMeter` must remain visual and state-driven, not rule-driven; -5. bank-family capacity logic remains outside both components. - -## Explicit Non-Decisions - -This decision does not yet define: - -- the Java package layout or exact class names for the first concrete asset-details subclass; -- the `Bank Composition` section shell layout details; -- the middleware/controller contract; -- the `workspaceBus` event contract; -- persistence or apply behavior. - -## Propagation Targets - -- Studio agendas: - [`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](../agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md) - [`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](../agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md) - [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md) - [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md) -- Studio specs: - [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- Studio code: - future component classes for `StudioDualListView`, the first asset-details concrete implementation, and `StudioAssetCapacityMeter` - -## Validation Notes - -Examples implied by this decision: - -- the right/build list can be reordered through `moveUp` and `moveDown`; -- the right/build list can display visible indices without requiring middleware-specific rendering logic; -- the capacity meter can show green, orange, or red state based on inputs from higher-level orchestration without knowing tile or sound rules. diff --git a/docs/studio/decisions/Bank Composition Details DTO Projection Decision.md b/docs/studio/decisions/Bank Composition Details DTO Projection Decision.md deleted file mode 100644 index e75dca26..00000000 --- a/docs/studio/decisions/Bank Composition Details DTO Projection Decision.md +++ /dev/null @@ -1,109 +0,0 @@ -# Bank Composition Details DTO Projection Decision - -Status: Decided -Cycle: 2026-03 -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Context - -The `Bank Composition` section inside `Asset Details` needs a stable UI-facing data shape before component, middleware, and persistence work can proceed. - -The source information comes from two distinct places: - -- runtime snapshot state derived from `walkResult`, which should feed `available` files; -- persisted `asset.json` composition state, which should feed `selected` files. - -The Studio should not bind section UI directly to snapshot internals or raw manifest structures. -This needs a Studio-owned DTO projection boundary. - -This decision closes the DTO direction discussed in: - -- [`Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md`](../agendas/Agenda-01-Asset-Bank-Composition-Snapshot-Transfer-to-Details-DTOs.md) - -## Decision - -Adopt one dedicated Studio-owned DTO family for `Bank Composition` details data. - -The first-wave projection rules are: - -1. snapshot rows derived from `walkResult` become `available` rows in the Studio DTO layer; -2. persisted composition rows from `asset.json` become `selected` rows in the Studio DTO layer; -3. both flows must be projected into Studio DTOs before reaching `Asset Details` UI code; -4. the DTO family must be generic enough to support any bank type, even if family-specific fields are added later; -5. the DTO field set must stay intentionally small and grow only when concrete UI behavior requires it. - -The first DTO revision starts with these fields: - -- `path` -- `displayName` -- `size` -- `lastModified` -- `fingerprint` -- `metadata` - -Availability and ordering rules are: - -1. only non-blocking files become `available` DTO rows; -2. blocking files must not be projected into the `Bank Composition` DTO layer; -3. UI ordering is visual in the selected list; -4. persisted ordering in `asset.json` should use an explicit index representation such as `{ file, index }`. - -## Justification - -This direction keeps the Studio UI decoupled from packer/runtime internal shapes while still using runtime data as the source of truth. - -One shared DTO family is the pragmatic middle ground: - -- lighter than separate `available` and `selected` row models; -- safer than direct binding to snapshot and manifest structures; -- easier to reuse across section shell, transfer list, meter, and staged editing middleware. - -Filtering blocking files before DTO projection also keeps the section contract simpler. -The UI should receive only rows that are actually eligible to appear as `available`. - -Persisted order needs an explicit index in `asset.json` because list order is not a robust persistence contract by itself. - -## Implications - -The Studio details layer now owns a DTO projection step for `Bank Composition`. - -This means: - -- component work should consume Studio DTOs, not packer snapshot rows directly; -- middleware work should operate on DTO-based staged state; -- persistence work must translate selected DTO order into indexed `asset.json` entries; -- packer-facing details fetches must expose enough source data to populate the DTO fields above. - -## Explicit Non-Decisions - -This decision does not yet define: - -- the exact Java classes or package layout for the DTOs; -- the section middleware/controller contract; -- the `workspaceBus` event contract; -- the concrete `asset.json` `artifacts` schema beyond the need for explicit indexed order; -- family-specific explanatory copy for tile versus sound exhaustion. - -## Propagation Targets - -- Studio agendas: - [`Agenda-02-Asset-Bank-Composition-Base-Components.md`](../agendas/Agenda-02-Asset-Bank-Composition-Base-Components.md) - [`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](../agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md) - [`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](../agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md) - [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md) - [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md) -- Studio specs: - [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- Studio code: - `Asset Details` details fetch, DTO projection layer, and `Bank Composition` section inputs -- Packer code and docs: - details payload shaping and future `asset.json` persistence under the `artifacts` composition path - -## Validation Notes - -Examples implied by this decision: - -- a file with blocking diagnostics does not produce an `available` DTO row at all; -- a selected file may appear in the UI with visual order `3`, while persistence writes something like `{ file: "...", index: 3 }`; -- adding new UI needs later should extend the DTO deliberately instead of pulling snapshot internals straight into the section. diff --git a/docs/studio/decisions/Bank Composition Middleware and Staged Editing Decision.md b/docs/studio/decisions/Bank Composition Middleware and Staged Editing Decision.md deleted file mode 100644 index 05d6e776..00000000 --- a/docs/studio/decisions/Bank Composition Middleware and Staged Editing Decision.md +++ /dev/null @@ -1,114 +0,0 @@ -# Bank Composition Middleware and Staged Editing Decision - -Status: Decided -Cycle: 2026-03 -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Context - -`Bank Composition` needs a section-scoped coordinator above the new UI components because: - -- `StudioDualListView` is intentionally dumb; -- `StudioAssetCapacityMeter` is intentionally dumb; -- the section must follow the same staged-edit model already used elsewhere in `Asset Details`; -- capacity and blocker rules differ by asset family. - -The current codebase already has a staged-edit primitive in: - -- [`StudioFormSession.java`](../../../prometeu-studio/src/main/java/p/studio/controls/forms/StudioFormSession.java) - -The earlier `Bank Composition` decisions already fixed: - -- DTO projection: - [`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md) -- base components: - [`Bank Composition Base Components Decision.md`](./Bank%20Composition%20Base%20Components%20Decision.md) -- section shell: - [`Bank Composition Section Shell Decision.md`](./Bank%20Composition%20Section%20Shell%20Decision.md) - -This decision closes the middleware direction discussed in: - -- [`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](../agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md) - -## Decision - -Adopt a dedicated bank-composition section-scoped coordinator built around `StudioFormSession`. - -The first-wave rules are: - -1. `StudioFormSession` is the shared staged-edit core for the section; -2. `Bank Composition` must not introduce a second session model parallel to `StudioFormSession`; -3. family-specific variation must not come from subclassing `StudioFormSession`; -4. family-specific variation must come from draft factories and bank-composition policies offered per asset family; -5. `apply` may remain stubbed or disabled until persistence is wired, but the session contract should already exist. - -The section-scoped coordinator owns orchestration around the form session, including: - -- translating persisted section state into session source/draft state; -- beginning edit mode; -- resetting draft state; -- canceling edits; -- applying draft state when persistence is available; -- evaluating transfer eligibility; -- evaluating reorder effects; -- calculating capacity state; -- calculating hard-limit blockers and hints. - -The section-scoped coordinator should publish one section-facing view model that includes: - -- shell state such as editing mode, dirty state, and action availability; -- left and right list state; -- capacity-meter state; -- blockers and hint text when relevant. - -## Justification - -This is the simplest design that matches the actual codebase. - -`StudioFormSession` already provides the staged-edit lifecycle the section needs. -Creating a second coordinator-specific session model would duplicate behavior for no gain. - -At the same time, subclassing `StudioFormSession` is the wrong variation point. -The current class is final, and more importantly the lifecycle does not change by asset family. -What changes by family is bank-composition logic: draft shaping, eligibility, capacity, and blockers. - -That makes policies and factories the correct seam. - -## Invariants and Constraints - -The following constraints now apply: - -1. `StudioFormSession` is the only staged-edit core for the section in the first wave; -2. asset-family differences must be modeled outside `StudioFormSession`; -3. the section-scoped coordinator remains section-specific and should not become a platform-wide bank manager abstraction; -4. dumb UI components consume derived state and do not own bank rules; -5. the section-facing output must be consolidated into one view model rather than scattered state channels. - -## Explicit Non-Decisions - -This decision does not yet define: - -- the exact Java class names or package layout for the section-scoped coordinator, policies, or draft factories; -- the exact shape of `BankCompositionDraft`; -- the `workspaceBus` event contract; -- persistence/apply integration with packer; -- the exact text of family-specific hint and blocker messages. - -## Propagation Targets - -- Studio agendas: - [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md) - [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md) -- Studio specs: - [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- Studio code: - `StudioFormSession` integration, `Bank Composition` section-scoped coordinator, family-specific draft factories, and family-specific bank-composition policies - -## Validation Notes - -Examples implied by this decision: - -- a tile family and a sound family can share the same `StudioFormSession` lifecycle while using different capacity/blocker policies; -- the dual list and meter can stay dumb because the section-scoped coordinator supplies already-derived state; -- when persistence is not wired yet, `beginEdit`, `reset`, and `cancel` still work through the shared form-session model. diff --git a/docs/studio/decisions/Bank Composition Persistence and Snapshot Propagation Decision.md b/docs/studio/decisions/Bank Composition Persistence and Snapshot Propagation Decision.md deleted file mode 100644 index 109fd43a..00000000 --- a/docs/studio/decisions/Bank Composition Persistence and Snapshot Propagation Decision.md +++ /dev/null @@ -1,120 +0,0 @@ -# Bank Composition Persistence and Snapshot Propagation Decision - -Status: Decided -Cycle: 2026-03 -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Context - -`Bank Composition` reaches across Studio and packer when the developer clicks `apply`. - -That write path must: - -- persist selected ordered files into `asset.json`; -- use the newer `artifacts` representation instead of the older `inputsByRole` shape; -- refresh enough runtime state for `Asset Details` to become consistent again after apply. - -The earlier `Bank Composition` decisions already fixed: - -- DTO projection: - [`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md) -- base components: - [`Bank Composition Base Components Decision.md`](./Bank%20Composition%20Base%20Components%20Decision.md) -- section shell: - [`Bank Composition Section Shell Decision.md`](./Bank%20Composition%20Section%20Shell%20Decision.md) -- middleware and staged editing: - [`Bank Composition Middleware and Staged Editing Decision.md`](./Bank%20Composition%20Middleware%20and%20Staged%20Editing%20Decision.md) -- workspace bus interaction: - [`Bank Composition WorkspaceBus Interaction Decision.md`](./Bank%20Composition%20WorkspaceBus%20Interaction%20Decision.md) - -This decision closes the persistence direction discussed in: - -- [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md) - -## Decision - -Route `Bank Composition` apply through packer and persist selection under `asset.json` `artifacts`. - -The first-wave rules are: - -1. Studio must not write `asset.json` directly; -2. the packer service owns validation, persistence, and minimal snapshot refresh for selected bank-composition files; -3. `artifacts` replaces the older `inputsByRole` representation for this flow; -4. selected file order must remain explicit in persisted data rather than relying on array position alone; -5. after a successful apply, Studio must refresh from persisted state rather than trusting stale draft state. - -The minimal successful apply flow is: - -1. Studio submits the selected ordered files to the packer service; -2. packer updates `asset.json` under the `artifacts` representation; -3. packer refreshes the minimal runtime snapshot state required by `Asset Details`; -4. Studio rebinds the section from that refreshed persisted state; -5. the section returns to consistent read-only mode. - -The minimum refreshed state after apply must include: - -- persisted `selected` rows; -- the current `available` projection used by `Asset Details`; -- recalculated capacity state; -- recalculated blockers or eligibility state relevant to the section. - -The failure rules are: - -1. if apply fails, the draft must not be discarded; -2. the section must remain in editing mode; -3. the middleware/controller should publish `BankCompositionApplyFailed`; -4. the UI should show a local failure surface; -5. the user must still be able to retry, reset, or cancel. - -## Justification - -This keeps write ownership in the correct domain boundary. - -Packer already owns asset mutation and runtime refresh logic. -Letting Studio write manifests directly would duplicate rules and create drift between UI and runtime behavior. - -The Studio should only submit the apply request and react to the result. -The packer service is the owner of validation, persistence, and state propagation. - -Refreshing from persisted state after success is also necessary. -Otherwise the section would keep trusting stale draft state and could diverge from what packer actually accepted and wrote. - -Preserving the draft on failure is the correct staged-edit behavior. -The user should not lose work because persistence failed. - -## Invariants and Constraints - -The following constraints now apply: - -1. Studio is not the manifest writer for `Bank Composition`; -2. `artifacts` is the persistence path for selected bank-composition files; -3. `inputsByRole` is not the write target for this flow; -4. successful apply requires snapshot refresh before the section settles back to read-only mode; -5. failed apply must preserve draft state and editing mode. - -## Explicit Non-Decisions - -This decision does not yet define: - -- the exact final `asset.json` `artifacts` schema beyond explicit ordered file persistence; -- the concrete packer request/response message names; -- the exact Java event class payloads for apply success or failure; -- broader manifest migration strategy outside this `Bank Composition` flow. - -## Propagation Targets - -- Studio specs: - [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- Studio code: - bank-composition apply flow, failure handling, and section refresh behavior -- Packer docs and code: - `asset.json` `artifacts` persistence, write-path integration, and minimal runtime snapshot refresh after apply - -## Validation Notes - -Examples implied by this decision: - -- after a successful apply, the section should reload from the refreshed persisted state instead of keeping the old draft instance; -- if packer rejects an apply, the selected rows remain in the draft so the user can adjust and retry; -- selected bank-composition files must be written through `artifacts`, not through `inputsByRole`. diff --git a/docs/studio/decisions/Bank Composition Section Shell Decision.md b/docs/studio/decisions/Bank Composition Section Shell Decision.md deleted file mode 100644 index f7205273..00000000 --- a/docs/studio/decisions/Bank Composition Section Shell Decision.md +++ /dev/null @@ -1,85 +0,0 @@ -# Bank Composition Section Shell Decision - -Status: Decided -Cycle: 2026-03 -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Context - -The `Bank Composition` area needs a visible section shell inside `Asset Details` before behavior and persistence are wired. - -The section should not invent a parallel editing model. -It needs to align with the existing `Asset Details` section rhythm, especially `Runtime Contract`. - -The DTO projection boundary and the first-wave component direction were already closed in: - -- [`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md) -- [`Bank Composition Base Components Decision.md`](./Bank%20Composition%20Base%20Components%20Decision.md) - -This decision closes the shell direction discussed in: - -- [`Agenda-03-Asset-Bank-Composition-Section-Shell.md`](../agendas/Agenda-03-Asset-Bank-Composition-Section-Shell.md) - -## Decision - -Create the `Bank Composition` section shell early, before full behavior is implemented. - -The shell contract is: - -1. `Bank Composition` is a `VBox` section inside `Asset Details`; -2. the section shell should mirror `Runtime Contract` as closely as practical at the JavaFX composition level; -3. the section should align with the existing `FormSession` staged-editing pattern; -4. the section header and action cluster must support `change`, `apply`, `reset`, and `cancel`; -5. the body layout must reserve the dual-list region on the left and the capacity-meter region on the right; -6. outside `change` mode, the section should render the current persisted state as read-only; -7. before middleware wiring exists, the section body should still render disabled or read-only internals rather than an empty placeholder. - -## Justification - -This keeps the editing model of `Asset Details` coherent. - -The developer should not need to learn one staged-edit contract for `Runtime Contract` and another for `Bank Composition`. -Using the same shell and `FormSession` rhythm lowers implementation risk and reduces UI inconsistency. - -Rendering the current persisted state in read-only mode is also the better default. -It teaches the surface, shows that data exists, and avoids making the section look unfinished or absent whenever editing is not active. - -## Invariants and Constraints - -The following constraints now apply: - -1. `Bank Composition` must exist as a real section shell before middleware behavior is complete; -2. the shell must follow the same staged-edit interaction model already used by `Runtime Contract`; -3. `FormSession` is part of the expected section lifecycle; -4. the section must not collapse into a blank placeholder when behavior is still incomplete; -5. the shell layout must already reflect the intended dual-list plus capacity-meter structure. - -## Explicit Non-Decisions - -This decision does not yet define: - -- the middleware/controller contract; -- the `workspaceBus` event contract; -- the exact disabled/read-only visuals of the early shell; -- apply persistence behavior; -- family-specific meter semantics beyond the already agreed general direction. - -## Propagation Targets - -- Studio agendas: - [`Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md`](../agendas/Agenda-04-Asset-Bank-Composition-Middleware-and-Staged-Editing.md) - [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md) - [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md) -- Studio specs: - [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- Studio code: - `AssetDetailsControl`, the future `Bank Composition` section control, and any `FormSession` integration needed for staged editing - -## Validation Notes - -Examples implied by this decision: - -- the section can appear in the details view even before middleware logic exists; -- the shell can show current selection state in read-only mode when the user has not entered `change`; -- the same section-level action rhythm used by `Runtime Contract` should apply to `Bank Composition`. diff --git a/docs/studio/decisions/Bank Composition WorkspaceBus Interaction Decision.md b/docs/studio/decisions/Bank Composition WorkspaceBus Interaction Decision.md deleted file mode 100644 index 9fa22062..00000000 --- a/docs/studio/decisions/Bank Composition WorkspaceBus Interaction Decision.md +++ /dev/null @@ -1,110 +0,0 @@ -# Bank Composition WorkspaceBus Interaction Decision - -Status: Decided -Cycle: 2026-03 -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Context - -The `Bank Composition` section should integrate with the Studio workspace event model, but the first-wave `workspaceBus` surface needs to stay intentionally small. - -The previous decisions already fixed: - -- DTO projection: - [`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md) -- base components: - [`Bank Composition Base Components Decision.md`](./Bank%20Composition%20Base%20Components%20Decision.md) -- section shell: - [`Bank Composition Section Shell Decision.md`](./Bank%20Composition%20Section%20Shell%20Decision.md) -- middleware and staged editing: - [`Bank Composition Middleware and Staged Editing Decision.md`](./Bank%20Composition%20Middleware%20and%20Staged%20Editing%20Decision.md) - -This decision closes the first-wave event direction discussed in: - -- [`Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md`](../agendas/Agenda-05-Asset-Bank-Composition-WorkspaceBus-Interaction.md) - -## Decision - -Adopt a minimal, notification-oriented first-wave `workspaceBus` contract for `Bank Composition`. - -The first-wave rules are: - -1. user actions should stay local to the bank-composition section-scoped coordinator whenever possible; -2. the first public `workspaceBus` surface should publish only state transitions or lifecycle notifications that matter outside the section; -3. the event contract must not encode bank-family product rules directly into event types; -4. capacity notifications should use absolute progress in the `0..1` range, not deltas. - -The first-wave public notification set is: - -- `BankCompositionDraftChanged` -- `BankCompositionCapacityChanged` -- `BankCompositionApplyRequested` -- `BankCompositionApplied` -- `BankCompositionApplyFailed` - -The first-wave local-only action set remains inside the section-scoped coordinator: - -- `beginEdit` -- `moveToSelected` -- `moveToAvailable` -- `moveUp` -- `moveDown` -- `reset` -- `cancel` -- `apply` - -`apply` should remain a local section action that calls the packer service. -It is not a public bus command in the first wave. - -The first-wave capacity notification should expose at least: - -- `progress` -- `severity` -- `blocked` - -## Justification - -This preserves the workspace event architecture without inflating the bus contract too early. - -If every section interaction became a public event, the bus would turn into a noisy command surface with little external value. -The section-scoped coordinator is already the right local place for section commands and recalculation. - -Absolute capacity state is also the right public shape. -It is easier to consume, easier to reason about, and safer for late subscribers than delta-based updates. - -## Invariants and Constraints - -The following constraints now apply: - -1. the first-wave public bus contract is notification-oriented, not command-oriented; -2. section-local interactions should not become public events unless another subscriber truly needs them; -3. capacity state must be published as absolute progress; -4. the bus contract must stay bank-family-neutral at the event-type level. - -## Explicit Non-Decisions - -This decision does not yet define: - -- the exact Java class names or package layout for the new events; -- the full payload shape of each event beyond the minimum capacity fields already fixed; -- whether future cross-section coordination will require more bus events; -- apply persistence semantics with packer. - -## Propagation Targets - -- Studio agendas: - [`Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md`](../agendas/Agenda-06-Asset-Bank-Composition-Persistence-and-Snapshot-Propagation.md) -- Studio specs: - [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- Studio code: - bank-composition section-scoped coordinator, event definitions, and event subscribers in `Asset Details` - -## Validation Notes - -Examples implied by this decision: - -- dragging or reordering inside the dual list does not require a public bus command in the first wave; -- the capacity meter can react to a published absolute progress state such as `0.72` with `orange` severity and `blocked=false`; -- apply success or failure can be observed outside the section without exposing every internal section action as a bus event; -- clicking `apply` should call the packer service locally and only publish lifecycle notifications around that operation. diff --git a/docs/studio/decisions/Pack Wizard in Assets Workspace Decision.md b/docs/studio/decisions/Pack Wizard in Assets Workspace Decision.md deleted file mode 100644 index ea7623bf..00000000 --- a/docs/studio/decisions/Pack Wizard in Assets Workspace Decision.md +++ /dev/null @@ -1,179 +0,0 @@ -# Pack Wizard in Assets Workspace Decision - -Status: Decided -Cycle: 2026-03 -Domain Owner: `docs/studio` -Cross-Domain Impact: `docs/packer` - -## Context - -The `Assets` workspace already reserves workspace-level action space for `Pack`, but the Studio did not yet have a closed decision for how that action should behave. - -The discussion is not about a button alone. -It is about the operational contract between Studio and packer when a developer wants to pack the current asset build set into `assets.pa`. - -The agenda that closed the discussion is: - -- [`Pack Wizard in Assets Workspace Agenda.md`](../agendas/Pack%20Wizard%20in%20Assets%20Workspace%20Agenda.md) - -Relevant upstream references are: - -- [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- [`../../packer/specs/4. Build Artifacts and Deterministic Packing Specification.md`](../../packer/specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md) -- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) - -This decision closes the boundary, flow, and first-wave gating rules for the `Pack` wizard. - -## Decision - -`Pack` in the `Assets` workspace is a Studio-owned modal shell over packer-owned operations. - -The first-wave decision is: - -1. clicking `Pack` opens a workspace-level modal wizard; -2. the wizard has four explicit phases: - `Summary`, `Validation`, `Packing`, and `Result`; -3. Studio owns presentation, navigation, and state binding for the modal; -4. packer owns summary generation, validation semantics, pack execution, progress, and result semantics; -5. the canonical emitted runtime artifact remains `assets.pa`; -6. the runtime-facing `asset_table` remains packer-owned and deterministic by increasing `asset_id`. - -## Operational Contract - -The Studio must call three distinct packer operations: - -1. `summary` -2. `validation` -3. `pack execution` - -These are separate calls, not one opaque long-running operation from the Studio point of view. - -The Studio must not start `pack execution` just to obtain summary or validation state. - -The packer may share internal implementation between those calls, but the Studio-facing API boundary must preserve the distinction. - -## Wizard Flow - -### Summary - -The `Summary` phase presents the current build set that would be packed. - -The minimum summary surface includes: - -- count of registered assets included in the current build set; -- count of assets outside the build set; -- explicit mention that the emitted runtime artifact is `assets.pa`; -- explicit mention that `asset_table` ordering follows deterministic `asset_id` ordering. - -Studio must not reconstruct the build set locally. -It presents packer-owned summary data. - -### Validation - -The `Validation` phase is a packer-owned dry-run-like validation over the pack set only. - -The pack set for this flow is: - -- registered assets; -- included in build. - -Validation rules: - -1. any blocking diagnostic in that set fails validation; -2. failed validation prevents transition into `Packing`; -3. warnings may be shown, but warnings do not block the first-wave pack unless packer explicitly classifies them as blocking; -4. the validation surface shows blocking diagnostics by default; -5. the developer may inspect additional asset context through drill-down, but the primary goal of the phase is to explain the gate. - -This validation is conceptually similar to a restricted deep-sync dry-run, but its scope is only the assets that actually participate in the pack. - -### Packing - -`Packing` is an operational, non-editable execution phase. - -Rules: - -1. the phase shows a progress bar and short current-step text; -2. progress must come from packer-owned progress events or structured progress state; -3. the Studio must not fake progress with timers; -4. the modal remains in an operant state until completion or failure; -5. the first wave does not support cancellation; -6. the UI must not present fake or misleading cancel behavior. - -### Result - -The `Result` phase summarizes the completed operation. - -The primary result summary includes: - -- final status; -- total assets packed; -- elapsed time; -- explicit reference to `assets.pa`. - -Companion artifacts are secondary detail. -They may appear in drill-down or expanded result detail, but they do not dominate the primary result summary. - -The result surface must distinguish: - -1. validation failure; -2. execution/generation failure; -3. persistence/emission failure. - -## Justification - -This keeps ownership aligned with the domain model. - -Studio is a shell and interaction layer. -Packer is the owner of build-set semantics, diagnostics classification, deterministic output ordering, progress semantics, and final artifact emission. - -Using distinct `Summary`, `Validation`, `Packing`, and `Result` phases also makes the flow didactic and operationally honest. -The developer can see what will be packed, why packing is blocked, when the operation is running, and what was emitted at the end. - -Keeping validation restricted to `registered + included in build` avoids ambiguity. -The wizard is about packing the active build set, not about re-auditing unrelated assets. - -Treating the first wave as non-cancelable is also the correct baseline. -The UI must not imply cancellation guarantees that the packer does not actually provide. - -## Invariants and Constraints - -The following constraints now apply: - -1. `Pack` is a workspace-level action, not a selected-asset action; -2. Studio is not the semantic owner of pack validation or execution; -3. Studio presents packer-owned data and results rather than recomputing them locally; -4. the pack set is the current `registered + included in build` set; -5. blocking diagnostics in that set stop the flow at `Validation`; -6. `Packing` is non-editable and non-cancelable in the first wave; -7. `assets.pa` remains the canonical artifact name in Studio-facing copy and contracts. - -## Explicit Non-Decisions - -This decision does not yet define: - -- the exact packer request and response type names; -- the exact event payload schema for progress and final result; -- whether a future wave should support exporting or copying failure summaries; -- whether a future wave should support real cooperative cancellation; -- the final visual styling of the wizard shell beyond the phase structure and behavior. - -## Propagation Targets - -- Studio specs: - [`4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- Studio plans and code: - the `Assets` workspace action bar, the future pack wizard shell, validation/result surfaces, and progress binding -- Packer plans, specs, and code: - summary API, validation API, pack execution API, progress contract, and result contract for Studio consumption -- Packer build artifacts: - `assets.pa` emission and related companion artifact reporting - -## Validation Notes - -Examples implied by this decision: - -- opening the modal should first request packer-owned summary data rather than locally counting navigator rows; -- if validation reports one included asset with blocking diagnostics, the wizard must remain blocked before `Packing`; -- if packing starts, the modal becomes operational and non-editable until the packer reports completion or failure; -- the primary result summary should mention `assets.pa` even if richer companion artifact details are also available. diff --git a/docs/studio/decisions/README.md b/docs/studio/decisions/README.md index f139d0dc..fca6b44c 100644 --- a/docs/studio/decisions/README.md +++ b/docs/studio/decisions/README.md @@ -1,17 +1,12 @@ # Studio Decisions -This directory contains Studio decision records. +This directory contains Studio decision records that still need propagation. -Current decision records: +Current retained set: -- [`Bank Composition Details DTO Projection Decision.md`](./Bank%20Composition%20Details%20DTO%20Projection%20Decision.md) -- [`Bank Composition Base Components Decision.md`](./Bank%20Composition%20Base%20Components%20Decision.md) -- [`Bank Composition Section Shell Decision.md`](./Bank%20Composition%20Section%20Shell%20Decision.md) -- [`Bank Composition Middleware and Staged Editing Decision.md`](./Bank%20Composition%20Middleware%20and%20Staged%20Editing%20Decision.md) -- [`Bank Composition WorkspaceBus Interaction Decision.md`](./Bank%20Composition%20WorkspaceBus%20Interaction%20Decision.md) -- [`Bank Composition Persistence and Snapshot Propagation Decision.md`](./Bank%20Composition%20Persistence%20and%20Snapshot%20Propagation%20Decision.md) +- none -The first Studio decision wave and the first asset workspace wave were already consolidated into: +The current Studio decision wave has already been consolidated into: - normative specifications under [`../specs/`](../specs/) - didactic material under [`../learn/`](../learn/) diff --git a/docs/studio/learn/README.md b/docs/studio/learn/README.md index 2e4740ec..2ab940e2 100644 --- a/docs/studio/learn/README.md +++ b/docs/studio/learn/README.md @@ -49,4 +49,8 @@ Start here: 1. [`mental-model-studio-shell.md`](./mental-model-studio-shell.md) 2. [`mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md) 3. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md) -4. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md) +4. [`assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md) +5. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md) +6. [`bank-composition-editor.md`](./bank-composition-editor.md) +7. [`pack-wizard-shell.md`](./pack-wizard-shell.md) +8. [`project-scoped-state-and-activity.md`](./project-scoped-state-and-activity.md) diff --git a/docs/studio/learn/assets-workspace-execution-wave.md b/docs/studio/learn/assets-workspace-execution-wave.md new file mode 100644 index 00000000..0734e51f --- /dev/null +++ b/docs/studio/learn/assets-workspace-execution-wave.md @@ -0,0 +1,88 @@ +# Assets Workspace Execution Wave + +## Original Problem + +The first `Assets` workspace wave solved many UI problems in small execution slices: + +- workspace foundation; +- asset navigator; +- selected-asset details; +- activity, progress, and logs; +- staged mutations; +- event-driven refactor; +- package and subscription boundaries. + +That historical sequence was useful while implementation was in flight, but it became a poor learning surface. + +## Consolidated Decision + +The stable Studio direction for `Assets` is: + +1. the workspace is asset-first, not file-first; +2. the workspace is event-driven, not refresh-heavy; +3. composition, projection, and rendering are separated; +4. details sections update independently instead of forcing whole-panel rebuilds; +5. mutation review is preview-first; +6. the shell reflects operational lifecycle without taking over workspace-local reasoning. + +## Final Model + +### 1. Workspace Foundation + +- `Assets` is a real workspace, not a placeholder; +- workspace state is explicit about loading, empty, error, and ready conditions; +- selection is stable by asset identity rather than by transient row position. + +### 2. Navigator and Details Split + +- the left side owns navigation and projection; +- the main area teaches the selected asset in a fixed didactic order; +- navigator updates and details updates must not require a workspace-wide redraw by default. + +### 3. Event-Driven Ownership + +- local UI change flows through typed workspace events; +- component-scoped subscriptions replace root-owned redraw logic; +- structural sync and local projection updates stay distinct. + +### 4. Operational Surfaces + +- activity belongs to the shell timeline; +- progress belongs both to the current workspace flow and the broader shell context; +- textual logs are supporting drill-down, not the main explanation surface. + +### 5. Mutation Review + +- preview is the default review surface for sensitive actions; +- blockers, warnings, and safe fixes remain semantically separate; +- modal confirmation is reserved for high-risk commit boundaries. + +## Examples + +### Example: Why the root should not own every redraw + +If one asset row changes because its diagnostics changed, the correct response is a row-scoped update. +Rebuilding navigator, details, and unrelated controls teaches the wrong ownership model and makes the UI harder to reason about. + +### Example: Why the shell still needs activity + +Mutation review happens inside the workspace. +But lifecycle milestones such as `preview ready`, `action applied`, or `action failed` still matter at shell scope because they are part of the user's project timeline. + +## Common Pitfalls and Anti-Patterns + +- Treating `Assets` as a filesystem explorer with extra badges. +- Using `refresh()` as the default answer to local UI state changes. +- Letting details sections depend on a monolithic selected-asset redraw. +- Using logs as the primary explanation surface for mutations. +- Publishing shell activity without keeping workspace-local review visible. + +## References + +- Specs: + - [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) + - [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) +- Related learn: + - [`./mental-model-assets-workspace.md`](./mental-model-assets-workspace.md) + - [`./mental-model-asset-mutations.md`](./mental-model-asset-mutations.md) + - [`./mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md) diff --git a/docs/studio/learn/bank-composition-editor.md b/docs/studio/learn/bank-composition-editor.md new file mode 100644 index 00000000..ebf2f893 --- /dev/null +++ b/docs/studio/learn/bank-composition-editor.md @@ -0,0 +1,126 @@ +# Bank Composition Editor + +## Original Problem + +`Bank Composition` needed to become a real editor inside `Asset Details` without collapsing into any of these bad outcomes: + +- direct binding to raw snapshot or manifest shapes; +- overgeneric UI components before the first section existed; +- family-specific rules hidden inside visual controls; +- direct Studio writes to `asset.json`; +- public bus chatter for every local section interaction. + +## Consolidated Decision + +The first-wave `Bank Composition` model is: + +1. Studio owns a DTO projection boundary for the section; +2. the section shell lands early and follows the existing staged-edit rhythm; +3. dual-list and capacity-meter components stay intentionally dumb; +4. one section-scoped coordinator around `StudioFormSession` owns orchestration; +5. public workspace-bus events stay minimal and notification-oriented; +6. `apply` goes through packer and rebinds from refreshed persisted state. + +## Final Model + +### 1. DTO Boundary + +The section never consumes raw packer/runtime structures directly. + +It works with Studio-owned DTOs for: + +- `available` rows from current runtime/details state; +- `selected` rows from persisted composition state. + +Only non-blocking files enter the `available` DTO projection. + +### 2. Section Shell + +`Bank Composition` is a real `Asset Details` section, not a hidden future placeholder. + +The shell follows the existing staged-edit rhythm: + +- `change` +- `apply` +- `reset` +- `cancel` + +Outside edit mode, it teaches the current persisted state in read-only form. + +### 3. Dumb Components + +Two named components exist for this area: + +- `StudioDualListView` +- `StudioAssetCapacityMeter` + +They are intentionally state-driven, not rule-driven. +Family-specific transfer, ordering, and capacity semantics do not live inside these components. + +### 4. Section-Scoped Coordinator + +The main orchestration lives in one section-scoped coordinator built around `StudioFormSession`. + +That coordinator owns: + +- draft lifecycle; +- transfer and reorder effects; +- capacity state; +- blockers and hints; +- apply success and failure handling. + +### 5. WorkspaceBus Boundary + +The public bus surface stays intentionally small. + +First-wave public notifications are about observable state transitions: + +- draft changed; +- capacity changed; +- apply requested; +- apply succeeded; +- apply failed. + +Local edit actions remain local to the section coordinator. + +### 6. Persistence Boundary + +Studio does not write `asset.json` directly for `Bank Composition`. + +The write path is: + +1. Studio submits ordered selected files to packer; +2. packer validates and persists through `asset.json.artifacts`; +3. packer refreshes the minimum runtime/details state; +4. Studio rebinds from refreshed persisted state. + +If apply fails, the draft stays alive and the section remains in editing mode. + +## Examples + +### Example: Why the meter must stay dumb + +Tile banks and sound banks may calculate capacity differently. +That difference belongs in family policies owned by the coordinator, not in `StudioAssetCapacityMeter`. + +### Example: Why `apply` is not a public bus command + +External observers may care that apply was requested or failed. +They do not need to own the local section command sequence for `moveUp`, `moveDown`, `reset`, or `cancel`. + +## Common Pitfalls and Anti-Patterns + +- Binding section UI directly to raw snapshot rows or raw manifest shape. +- Hiding bank-family rules inside `StudioDualListView` or the capacity meter. +- Creating a second staged-edit session model parallel to `StudioFormSession`. +- Turning every local section action into a public workspace-bus event. +- Writing `asset.json` directly from Studio instead of routing through packer. + +## References + +- Specs: + - [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) +- Cross-domain: + - [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) +- Related learn: + - [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md) diff --git a/docs/studio/learn/pack-wizard-shell.md b/docs/studio/learn/pack-wizard-shell.md new file mode 100644 index 00000000..200a74ae --- /dev/null +++ b/docs/studio/learn/pack-wizard-shell.md @@ -0,0 +1,87 @@ +# Pack Wizard Shell + +## Original Problem + +The `Assets` workspace already had a reserved `Pack` action, but that did not answer the real product question: + +How should Studio behave when the developer wants to pack the current build set? + +The risk was building a visually plausible modal that quietly reimplemented packer semantics or hid the real operational phases. + +## Consolidated Decision + +The stable first-wave rule is: + +`Pack` is a Studio-owned wizard shell over packer-owned operations. + +The wizard is phase-based: + +1. `Summary` +2. `Validation` +3. `Packing` +4. `Result` + +Studio owns presentation and state binding. +Packer owns summary, validation, execution, progress, and result semantics. + +## Final Model + +### 1. Workspace-Level Entry Point + +- `Pack` is a workspace action, not a selected-asset action; +- the user is operating on the current pack set, not on one asset in isolation. + +### 2. Summary + +- the wizard asks packer for the current build-set summary; +- Studio does not count navigator rows and pretend that is the build set; +- the canonical runtime artifact is explicitly `assets.pa`. + +### 3. Validation + +- validation runs only on `registered + included in build`; +- blocking diagnostics stop the flow before execution; +- warnings may be visible, but they do not become blockers unless packer classifies them that way. + +### 4. Packing + +- execution is operational and non-editable; +- progress comes from packer-owned progress state or events; +- the UI does not simulate progress with timers; +- the first wave is non-cancelable. + +### 5. Result + +- the primary summary shows final status, packed asset count, elapsed time, and `assets.pa`; +- companion artifacts are supporting detail, not the headline of the result screen; +- the UI must distinguish blocked, failed, and successful outcomes. + +## Examples + +### Example: Why validation is a separate phase + +If the wizard jumps straight from summary into execution, the user loses the explicit gate that explains why packing is blocked. +Validation exists to make the gate understandable before byte emission begins. + +### Example: Why Studio must not fake progress + +A fake progress bar may look smoother, but it lies about operational ownership. +If the packer is the owner of execution semantics, the UI must reflect packer-owned progress honestly. + +## Common Pitfalls and Anti-Patterns + +- 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 that the packer does not actually support. +- Making companion artifacts dominate the main result summary. + +## References + +- Specs: + - [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) +- Cross-domain: + - [`../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md`](../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md) + - [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md) +- Related learn: + - [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md) diff --git a/docs/studio/learn/project-scoped-state-and-activity.md b/docs/studio/learn/project-scoped-state-and-activity.md new file mode 100644 index 00000000..2e61aeb6 --- /dev/null +++ b/docs/studio/learn/project-scoped-state-and-activity.md @@ -0,0 +1,57 @@ +# Project-Scoped State and Activity + +## Original Problem + +Some Studio state is global by nature, but some state is clearly tied to one opened project. + +If project-local state is stored as if it were application-global, the shell starts mixing unrelated histories and the project root stops being the obvious home of Studio-owned project data. + +## Consolidated Decision + +The stable direction is: + +1. project-local Studio state lives under `.studio/` inside the project root; +2. shell activity is restored and persisted per project; +3. persisted activity history is bounded; +4. `.studio/` is the reserved root for future project-local Studio settings. + +## Final Model + +### 1. Storage Root + +- each project owns `.studio/`; +- new-project scaffolding creates that directory; +- `.workspace/` is not the project-local Studio root for this model. + +### 2. Activity Persistence + +- shell activity is loaded when the project opens; +- new activity is appended to that project's local history; +- history is trimmed to the latest `500` entries. + +### 3. Scope Rule + +- project-local shell history belongs to the project; +- launcher-global concerns remain outside this storage path; +- future Studio project configuration can live under the same `.studio/` root. + +## Examples + +### Example: Why activity cannot stay application-global + +If two projects have one shared persisted feed, the shell stops teaching the user what happened in the currently opened project. +That destroys causality instead of preserving it. + +## Common Pitfalls and Anti-Patterns + +- Treating project activity as if it were launcher-global state. +- Mixing unrelated projects into one persisted activity history. +- Leaving project-local Studio files in ad hoc roots instead of `.studio/`. +- Letting unbounded activity persistence grow without a hard cap. + +## References + +- Specs: + - [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) +- Related learn: + - [`./mental-model-studio-shell.md`](./mental-model-studio-shell.md) diff --git a/docs/studio/pull-requests/PR-05a-assets-workspace-foundation-and-service-state.md b/docs/studio/pull-requests/PR-05a-assets-workspace-foundation-and-service-state.md deleted file mode 100644 index d802187c..00000000 --- a/docs/studio/pull-requests/PR-05a-assets-workspace-foundation-and-service-state.md +++ /dev/null @@ -1,71 +0,0 @@ -# PR-05a Assets Workspace Foundation and Service State - -## Briefing - -Implement the first executable slice of the `Assets` workspace based on: - -- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) - -This PR creates the workspace foundation, service-facing state model, and event wiring required by all later `Assets` workspace slices. - -## Objective - -Replace the current `WorkspaceId.ASSETS` placeholder with a concrete `AssetsWorkspace` foundation that can: - -- boot inside the Studio shell, -- request and refresh asset data from Studio-facing services, -- maintain stable selection state, -- surface loading/empty/error states, -- and expose internal state in a way that later UI slices can reuse. - -## Dependencies - -- existing Studio shell and event bus foundations -- existing packer-facing Studio contracts and specifications - -## Scope - -- create a concrete `AssetsWorkspace` -- define workspace-local view state models for: - - navigator state - - selected asset state - - loading/error state -- define service-facing DTO adapters needed by the workspace -- define workspace event publications for asset refresh and selection updates -- integrate the workspace into the existing shell/workspace switch flow - -## Non-Goals - -- no final asset navigator visuals yet -- no final preview rendering yet -- no final staged mutation UI yet -- no production-grade packer backend implementation if stubs or adapters are still required - -## Execution Method - -1. Replace the placeholder assets workspace with a concrete class and root layout. -2. Introduce workspace-local state objects for navigator, selection, and detail hydration. -3. Introduce a Studio-facing service boundary for loading asset collections and selected-asset details. -4. Wire the workspace into `StudioWorkspaceEventBus` for refresh and selection lifecycle. -5. Define stable loading, empty, no-results, and error states in code. - -## Acceptance Criteria - -- selecting `Assets` opens a real workspace rather than a placeholder -- the workspace can request asset data through a Studio service boundary -- loading, empty, and error states are visible and distinct -- selection state is modelled explicitly and can be preserved by identity -- the workspace has enough state structure to support the later navigator and details PRs without redesign - -## Validation - -- unit tests for workspace state transitions -- unit tests for selection retention logic -- UI smoke validation that the Assets workspace mounts cleanly in the shell - -## Affected Artifacts - -- `prometeu-studio` workspace classes -- Studio event wiring -- Studio-facing asset service abstractions -- tests for workspace state and selection behavior diff --git a/docs/studio/pull-requests/PR-05b-asset-navigator-search-filters-and-selection.md b/docs/studio/pull-requests/PR-05b-asset-navigator-search-filters-and-selection.md deleted file mode 100644 index 6135b372..00000000 --- a/docs/studio/pull-requests/PR-05b-asset-navigator-search-filters-and-selection.md +++ /dev/null @@ -1,72 +0,0 @@ -# PR-05b Asset Navigator Search Filters and Selection - -## Briefing - -Implement the left-side `Asset Tree` / `Asset Navigator` for the `Assets` workspace. - -This PR applies the navigator and selection rules from: - -- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) - -## Objective - -Deliver the first concrete asset navigator with: - -- asset-first grouped navigation -- semantic filters -- textual search -- stable single selection -- explicit loading/empty/no-results/error states - -## Dependencies - -- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md) - -## Scope - -- implement the custom visual asset navigator control -- render group nodes and asset nodes -- implement baseline filters: - - `Managed` - - `Orphan` - - `Diagnostics` - - `Preload` -- implement textual search over asset name and path context -- preserve selection by `asset_id` or orphan root path as appropriate -- allow optional expansion into asset inputs only as supporting inspection - -## Non-Goals - -- no final selected-asset details composition yet -- no final mutation staging UI yet -- no heavy sorting or multi-select support - -## Execution Method - -1. Implement the navigator control and node rendering model. -2. Add the baseline filters and search composition logic. -3. Add stable selection reconciliation during refresh. -4. Add explicit navigator states for loading, empty, no-results, and workspace error. -5. Add the visual markers for managed/orphan, diagnostics, preload, and broad asset family. - -## Acceptance Criteria - -- the `Assets` workspace shows a real asset navigator on the left -- assets are grouped by path-aware structure without degrading into a raw file tree -- filters and search work together -- selection remains stable across refresh when identity is preserved -- orphan assets appear in the same navigator flow with clearly differentiated styling - -## Validation - -- unit tests for filter/search composition -- unit tests for selection preservation rules -- UI smoke validation for node rendering and navigator states - -## Affected Artifacts - -- `AssetsWorkspace` -- custom navigator controls -- navigator view models -- selection reconciliation logic -- tests for filters, search, and selection behavior diff --git a/docs/studio/pull-requests/PR-05c-selected-asset-details-contract-and-preview.md b/docs/studio/pull-requests/PR-05c-selected-asset-details-contract-and-preview.md deleted file mode 100644 index 8ed623a9..00000000 --- a/docs/studio/pull-requests/PR-05c-selected-asset-details-contract-and-preview.md +++ /dev/null @@ -1,80 +0,0 @@ -# PR-05c Selected Asset Details Contract and Preview - -## Briefing - -Implement the selected-asset details surface in the required fixed order: - -1. `Summary` -2. `Runtime Contract` -3. `Inputs / Preview` -4. `Diagnostics` -5. `Actions` - -This PR materializes the didactic core of the `Assets` workspace. - -## Objective - -Deliver the first usable selected-asset details experience, including: - -- summary identity/state rendering -- runtime-facing contract rendering -- inputs-by-role rendering -- first previewable input surfaces -- inline diagnostics -- action groups with routine vs sensitive separation - -## Dependencies - -- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md) -- [`./PR-05b-asset-navigator-search-filters-and-selection.md`](./PR-05b-asset-navigator-search-filters-and-selection.md) - -## Scope - -- render the fixed details skeleton -- render summary metadata and location -- render runtime contract fields such as `output.format`, `codec`, and `preload` -- render input groups and input selection -- implement first preview surfaces for previewable inputs -- render inline diagnostics by severity -- render action groups for: - - `Doctor` - - `Build` - - `Adopt` - - `Register` - - sensitive operations placeholders where needed - -## Non-Goals - -- no final staged preview/apply workflow yet -- no final lower log integration yet -- no exhaustive preview support for every asset family - -## Execution Method - -1. Build the selected-asset details layout in the mandated section order. -2. Render summary and runtime contract from workspace state. -3. Implement inputs-by-role rendering and input selection. -4. Implement baseline preview handling for previewable types. -5. Render inline diagnostics and action grouping. - -## Acceptance Criteria - -- selecting an asset hydrates a full details view in the fixed section order -- runtime-facing contract fields are visible without raw JSON inspection -- previewable inputs can be inspected from the details area -- diagnostics are visible inline and differentiated by severity -- routine actions and sensitive actions are visibly separated - -## Validation - -- unit tests for selected-asset detail mapping -- unit tests for action availability by asset state -- UI smoke validation for previewable input rendering - -## Affected Artifacts - -- `AssetsWorkspace` details area -- preview components -- diagnostics rendering -- action surface wiring -- tests for selected-asset detail behavior diff --git a/docs/studio/pull-requests/PR-05d-assets-activity-progress-and-logs-integration.md b/docs/studio/pull-requests/PR-05d-assets-activity-progress-and-logs-integration.md deleted file mode 100644 index 99d5c234..00000000 --- a/docs/studio/pull-requests/PR-05d-assets-activity-progress-and-logs-integration.md +++ /dev/null @@ -1,63 +0,0 @@ -# PR-05d Assets Activity Progress and Logs Integration - -## Briefing - -Integrate the `Assets` workspace with Studio activity, progress, and logs according to the assets workspace specification. - -## Objective - -Make the `Assets` workspace operationally legible by wiring: - -- structured activity into the shell right-side panel -- contextual progress into the workspace -- detailed textual logs into the lower region -- failure retention and acknowledgement surfaces where required - -## Dependencies - -- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md) -- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md) - -## Scope - -- map asset-service events into Studio activity entries -- aggregate repetitive background events into user-facing summaries -- wire `progress_updated` into progress surfaces without feed spam -- expose lower-region textual logs for asset operations -- retain recent actionable failures until acknowledgement -- mirror selected-asset failures inline where applicable - -## Non-Goals - -- no generic all-workspace activity framework redesign beyond what Assets needs now -- no final cross-workspace logs unification - -## Execution Method - -1. Define asset-workspace activity mapping rules. -2. Wire workspace and global bus publications for asset activity. -3. Implement feed aggregation for repetitive events. -4. Implement inline progress and lower-region logs integration. -5. Retain and surface actionable failures across shell and workspace surfaces. - -## Acceptance Criteria - -- asset events appear in the global `Activity` feed as user-oriented entries -- progress updates do not spam the feed -- logs are visible in the lower region for technical drill-down -- actionable failures remain visible until acknowledged -- selected-asset failures also appear inline when relevant - -## Validation - -- unit tests for activity aggregation mapping -- unit tests for failure retention logic -- UI smoke validation for shell/workspace activity interplay - -## Affected Artifacts - -- activity event adapters -- progress surfaces -- workspace log region integration -- failure retention state -- tests for activity mapping and failure behavior diff --git a/docs/studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md b/docs/studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md deleted file mode 100644 index a4cbb35c..00000000 --- a/docs/studio/pull-requests/PR-05e-assets-staged-mutations-preview-and-apply.md +++ /dev/null @@ -1,75 +0,0 @@ -# PR-05e Assets Staged Mutations Preview and Apply - -## Briefing - -Implement the preview-first mutation flows for the `Assets` workspace. - -This PR applies the staged mutation rules from: - -- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) - -## Objective - -Deliver inline staged mutation review for sensitive asset operations, including: - -- preview generation -- blockers, warnings, and safe-fix separation -- registry vs workspace impact explanation -- apply gating -- activity integration for preview/apply lifecycle - -## Dependencies - -- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md) -- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md) -- [`./PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md) - -## Scope - -- implement inline staged review panel inside the `Assets` workspace -- support preview-first handling for: - - `Adopt` - - `Forget` - - `Remove` - - `Quarantine` - - relocational mutations - - batch mutations when available -- render proposed actions, blockers, warnings, safe fixes, and diff-style effects -- disable `Apply` while blockers exist -- use modal confirmation only for high-risk final commits - -## Non-Goals - -- no fully generic mutation framework for every Studio workspace -- no speculative batch authoring flows that do not yet exist in services - -## Execution Method - -1. Define the staged review panel and its state model. -2. Integrate preview requests and preview-ready responses from services. -3. Render registry impact and workspace impact separately. -4. Gate apply on blockers. -5. Wire `preview_ready`, `action_applied`, and `action_failed` into activity. -6. Add modal confirmation only where the final commit is high-risk. - -## Acceptance Criteria - -- sensitive asset mutations do not execute directly from a single click -- preview clearly shows what will change in registry and workspace -- blockers prevent apply -- safe fixes remain visually distinct from destructive actions -- preview/apply lifecycle events surface correctly in workspace and activity - -## Validation - -- unit tests for preview state mapping and apply gating -- unit tests for registry/workspace impact rendering rules -- UI smoke validation for staged mutation flows - -## Affected Artifacts - -- staged review panel -- asset mutation action wiring -- preview/apply state models -- activity integration for mutation lifecycle -- tests for preview and apply behavior diff --git a/docs/studio/pull-requests/PR-06-project-scoped-studio-state-and-activity-persistence.md b/docs/studio/pull-requests/PR-06-project-scoped-studio-state-and-activity-persistence.md deleted file mode 100644 index 475784ad..00000000 --- a/docs/studio/pull-requests/PR-06-project-scoped-studio-state-and-activity-persistence.md +++ /dev/null @@ -1,111 +0,0 @@ -# PR-06 Project-Scoped Studio State and Activity Persistence - -Domain owner: `docs/studio` - -## Briefing - -Move Studio-local project persistence under each project root and make shell activity durable per project. - -The target model is: - -- each project owns a `.studio/` directory; -- `.studio/` is created when a new project is created; -- shell activity is stored inside that project-local directory and restored when the project is opened; -- activity retention is capped at a fixed maximum of `500` entries; -- the same `.studio/` root becomes the reserved home for future Studio project configuration. - -## Objective - -Make Studio state project-scoped instead of application-global where the data is inherently tied to one project, starting with activity persistence and the project-local Studio storage root. - -After this change: - -- opening a project reloads its recent activity feed; -- new activity entries are appended to that project's persisted history; -- persisted history is trimmed to the latest `500` entries; -- newly created projects already contain the `.studio/` structure expected by Studio. - -## Dependencies - -- [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md) -- current project creation flow in `ProjectCatalogService` -- current shell activity mapping and rendering in `StudioActivityFeedControl` - -## Scope - -- define the project-local Studio storage convention under `.studio/` -- persist shell activity entries per project -- restore persisted activity when a project shell opens -- enforce a hard retention cap of `500` entries -- create `.studio/` during new-project scaffolding -- reserve `.studio/` as the home for future project-local Studio settings -- replace the current scaffolded `.workspace/` directory with `.studio/` - -## Non-Goals - -- no redesign of activity event semantics or severity mapping -- no cross-project merged activity history -- no migration of global launcher data such as known projects -- no broad persistence pass for every workspace in this PR -- no attempt to define every future file that may live under `.studio/` - -## Execution Method - -1. Define the `.studio/` storage contract for Studio-owned project data. - Proposed baseline layout: - - `.studio/activities.json` for persisted shell activity history - - `.studio/settings.json` reserved for project-local Studio configuration - -2. Introduce a small project-local storage path abstraction. - It should centralize resolution of `.studio/`, activity storage, and future settings storage from `ProjectReference.rootPath()`. - -3. Add an activity persistence service/repository. - Responsibilities: - - load persisted entries for a project; - - store entries after append; - - normalize malformed or missing files into an empty history; - - trim persisted and in-memory history to the latest `500` records. - -4. Refactor `StudioActivityFeedControl` to become project-aware at construction time. - The control should: - - hydrate its initial list from persisted project activity; - - append new mapped entries to memory and persistence; - - preserve the existing duplicate-suppression behavior unless it conflicts with durable history expectations. - -5. Update shell composition to pass the active `ProjectReference` into the activity feed. - `MainView` should instantiate the feed for the currently opened project instead of a project-agnostic global feed. - -6. Update project creation scaffolding. - `ProjectCatalogService.createProject(...)` must create `.studio/` and stop creating `.workspace/`. - If needed, opening an older project may lazily create `.studio/` on first persistence write. - -7. Propagate the contract to Studio specs and tests. - The shell spec should state that shell activity is project-scoped, restored on open, and retained with a bounded history. - -## Acceptance Criteria - -- opening a project with an existing `.studio/activities.json` restores that project's recent activity feed before new events arrive -- activity produced while a project is open is persisted under that project's `.studio/` directory -- persisted activity history never exceeds `500` entries -- newly created projects contain `.studio/` -- new-project tests no longer expect `.workspace/` -- opening a project without `.studio/activities.json` still works and initializes an empty feed - -## Validation - -- unit tests for project scaffolding asserting `.studio/` creation -- unit tests for activity storage load/save behavior -- unit tests for retention trimming to `500` -- unit tests for activity-feed hydration from persisted entries -- unit tests for malformed or missing activity storage fallback -- smoke validation opening two different projects and confirming isolated activity histories - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/projects/ProjectCatalogService.java` -- `prometeu-studio/src/main/java/p/studio/window/MainView.java` -- `prometeu-studio/src/main/java/p/studio/controls/shell/StudioActivityFeedControl.java` -- new Studio project-storage service/repository classes under `prometeu-studio/src/main/java/p/studio/...` -- `prometeu-studio/src/test/java/p/studio/projects/ProjectCatalogServiceTest.java` -- new activity persistence tests under `prometeu-studio/src/test/java/p/studio/...` -- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md` diff --git a/docs/studio/pull-requests/PR-07a-assets-event-topology-and-lifecycle-foundation.md b/docs/studio/pull-requests/PR-07a-assets-event-topology-and-lifecycle-foundation.md deleted file mode 100644 index d6ab3968..00000000 --- a/docs/studio/pull-requests/PR-07a-assets-event-topology-and-lifecycle-foundation.md +++ /dev/null @@ -1,124 +0,0 @@ -# PR-07a Assets Event Topology and Lifecycle Foundation - -Domain owner: `docs/studio` - -## Briefing - -Refactor the `Assets` workspace foundation away from a monolithic `AssetWorkspace` that redraws major regions after local changes. - -This slice establishes the corrective architectural direction for the Studio as a whole. - -`Assets` is the first consumer and proving ground, but the target is not an `Assets`-only pattern. - -The Studio-standard direction is: - -- lifecycle-aware UI components; -- typed workspace events as the update mechanism; -- component-scoped subscriptions; -- explicit separation between structural workspace sync and local UI projection updates; -- reusable workspace framework pieces that other Studio workspaces must consume instead of inventing their own refresh-heavy flow. - -## Objective - -Create the event-driven workspace foundation required for all later `Assets` refactor slices and establish it as the correct Studio-wide pattern for workspace implementation. - -After this PR: - -- the workspace root coordinates composition instead of owning every region render path; -- navigator, row, details, and details-internal controls can subscribe independently; -- the workspace event bus becomes the primary update path for UI change propagation; -- `refresh()` is no longer the default answer for local state changes. -- the extracted lifecycle/event-driven primitives are designed for reuse by non-`Assets` workspaces. - -## Dependencies - -- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md) -- existing `StudioWorkspaceEventBus` -- existing `StudioControlLifecycle` support - -## Scope - -- define the target event topology for the `Assets` workspace -- define the target event topology as the canonical Studio workspace model -- split workspace responsibilities between composition, state coordination, and component rendering -- extract reusable workspace framework primitives where the abstraction is already justified by the `Assets` refactor -- introduce lifecycle-aware component boundaries for: - - navigator host - - asset-list host - - asset-row item - - details host - - details-local sections/forms -- introduce reusable patterns or base components for: - - workspace composition roots - - lifecycle-managed event subscribers - - projection host controls - - structural-sync versus local-patch orchestration -- define typed events for: - - structural snapshot changes - - projection changes - - selection changes - - selected-asset details lifecycle - - local patch propagation -- demote global redraw events to transitional or removable status - -## Non-Goals - -- no final navigator visuals redesign in this slice -- no final details-panel redesign in this slice -- no mutation-semantics redesign beyond event routing needs -- no broad shell-level event-system rewrite outside `Assets` -- no fake generalization disconnected from concrete `Assets` usage - -## Execution Method - -1. Define the component tree and ownership model. - The workspace root should compose controls and services, not render every region inline. - -2. Introduce event contracts for the asset workspace projection model. - The baseline contract should distinguish: - - structural workspace sync events - - navigator projection events - - selected-asset details events - - per-asset patch events - -3. Convert `AssetWorkspace` into a composition root plus orchestration layer. - It may still coordinate service calls, but rendering responsibilities should move into dedicated controls. - -4. Extract reusable workspace-framework pieces while doing the refactor. - `Assets` should consume the same primitives that future Studio workspaces are expected to consume. - -5. Require lifecycle installation for event-consuming controls. - Every component that subscribes to workspace events must implement `StudioControlLifecycle` and subscribe only while attached to the scene. - -6. Mark the existing redraw-request pattern as transitional. - `StudioAssetsNavigatorRedrawRequestedEvent` and `StudioAssetsDetailsRedrawRequestedEvent` should no longer be the target architecture. - -7. Propagate the rule to Studio documentation. - The resulting plans/spec updates should make clear that future workspaces are expected to build on this framework instead of introducing workspace-local refresh architecture. - -## Acceptance Criteria - -- the refactor has a clear component topology instead of one render-heavy workspace class -- lifecycle-aware controls own their own subscriptions -- the workspace event bus carries typed update events that components can consume independently -- local UI changes can be expressed without a full workspace refresh path -- the old redraw-request events are either removed or isolated behind temporary compatibility adapters -- the extracted primitives are reusable by other Studio workspaces -- the plan explicitly establishes this direction as the Studio-standard workspace architecture - -## Validation - -- unit tests for event routing between composition root and child controls -- unit tests for lifecycle subscribe/unsubscribe behavior on workspace controls -- smoke validation that mounting and unmounting the workspace does not leak subscriptions - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java` -- new reusable workspace-framework classes under `prometeu-studio/src/main/java/p/studio/...` -- new `Assets` workspace controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` -- `prometeu-studio/src/main/java/p/studio/events/...` -- `docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md` -- `docs/studio/specs/3. Studio Components Module Specification.md` -- tests for workspace event topology and lifecycle behavior diff --git a/docs/studio/pull-requests/PR-07b-asset-navigator-and-row-subscriptions.md b/docs/studio/pull-requests/PR-07b-asset-navigator-and-row-subscriptions.md deleted file mode 100644 index b7b2ecc0..00000000 --- a/docs/studio/pull-requests/PR-07b-asset-navigator-and-row-subscriptions.md +++ /dev/null @@ -1,75 +0,0 @@ -# PR-07b Asset Navigator and Row Subscriptions - -Domain owner: `docs/studio` - -## Briefing - -Refactor the navigator side of the `Assets` workspace so the list and each asset row update through event subscriptions instead of workspace-wide rerendering. - -## Objective - -Make navigator behavior event-directed and component-local. - -After this PR: - -- the navigator list subscribes to projection changes it actually needs; -- each asset row subscribes to row-scoped summary/selection updates; -- search and filters change the navigator projection without rebuilding the whole workspace; -- selection styling and row patching happen without forcing a full list refresh from the workspace root. -- the navigator and row patterns are implemented in a way that other Studio workspaces can reuse for list/detail navigation surfaces. - -## Dependencies - -- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md) -- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) - -## Scope - -- extract the navigator into dedicated controls -- separate navigator projection calculation from visual control ownership -- introduce row-scoped subscriptions and row identity handling -- keep reusable list/projection primitives outside `Assets`-only naming where they are genuinely cross-workspace -- publish projection updates for: - - search changes - - filter changes - - structural asset collection changes - - per-asset summary patches - - selection changes -- remove direct row bookkeeping from the workspace root where possible - -## Non-Goals - -- no details-panel refactor in this slice -- no final mutation confirmation flow refactor in this slice -- no broad service-layer redesign beyond what navigator subscriptions require - -## Execution Method - -1. Introduce an `AssetNavigatorControl` or equivalent host with lifecycle-managed subscriptions. -2. Extract row rendering into an `AssetRowControl` or equivalent lifecycle-managed component. -3. Move search/filter handling to event publication plus projection recalculation. -4. Publish selection updates as typed events that row controls can consume directly. -5. Replace root-owned row maps and manual selection restyling with row-scoped update flow. - -## Acceptance Criteria - -- asset rows are no longer rebuilt by default on every local navigator change -- search and filter changes update the navigator projection only -- selecting an asset updates only the controls that depend on selection -- patching one asset summary updates the affected row without requiring a full workspace reload -- navigator controls subscribe and unsubscribe through the lifecycle support -- reusable navigator/list subscription patterns are left available for future Studio workspaces - -## Validation - -- unit tests for navigator projection event flow -- unit tests for row identity stability across patches -- unit tests for selection update behavior without full projection rebuild -- UI smoke validation for search, filters, and selection transitions - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java` -- new navigator and row controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` -- `prometeu-studio/src/main/java/p/studio/events/...` -- tests for navigator projection and row update behavior diff --git a/docs/studio/pull-requests/PR-07c-asset-details-and-form-lifecycle.md b/docs/studio/pull-requests/PR-07c-asset-details-and-form-lifecycle.md deleted file mode 100644 index b07e70f4..00000000 --- a/docs/studio/pull-requests/PR-07c-asset-details-and-form-lifecycle.md +++ /dev/null @@ -1,82 +0,0 @@ -# PR-07c Asset Details and Form Lifecycle - -Domain owner: `docs/studio` - -## Briefing - -Refactor the selected-asset details side so the details host and its internal sections/forms subscribe only to the state they need. - -This slice explicitly covers the problem called out in the current direction: - -- the selected-asset details host must not own all redraws; -- each internal section/form must update from events instead of full details rebuilds. - -## Objective - -Make the details area componentized, lifecycle-aware, and event-driven. - -After this PR: - -- summary/actions, runtime contract, inputs/preview, diagnostics, and mutation-preview sections can update independently; -- details load state, ready state, and error state are event-driven; -- local form interactions such as preload toggles or preview selection do not rebuild unrelated details content; -- internal controls subscribe only while mounted. -- the details-section and form-subscription patterns become reusable Studio workspace primitives where appropriate. - -## Dependencies - -- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md) -- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md) -- [`./PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md) - -## Scope - -- extract the details host into dedicated controls -- split details content into lifecycle-aware sections -- extract reusable section-host and form-event patterns when they are not asset-specific -- define details events for: - - details loading started - - details ready - - details failed - - local summary patch applied - - preview input changed - - preview zoom changed - - mutation preview state changed -- route details-local form actions through the workspace bus instead of root-owned imperative redraw - -## Non-Goals - -- no navigator refactor in this slice -- no shell activity redesign in this slice -- no cross-workspace form framework extraction unless needed by the `Assets` details controls - -## Execution Method - -1. Introduce a dedicated details host control with lifecycle-managed subscriptions. -2. Extract stable details sections into separate controls. -3. Move details load and error transitions to typed events. -4. Route details-local interactions through narrow events and local state holders. -5. Remove root-level details reconstruction for interactions that affect only one section. - -## Acceptance Criteria - -- the selected-asset details view is no longer rebuilt as one large region for section-local changes -- forms and preview controls update independently -- details-ready and details-error transitions are observable through typed events -- details-local subscriptions are owned by the mounted controls, not the workspace root -- changing one local control does not force unrelated details sections to rerender -- reusable details/form lifecycle patterns are available for future Studio workspaces - -## Validation - -- unit tests for details lifecycle event flow -- unit tests for section-local updates -- unit tests for preload-toggle or equivalent form patch behavior -- UI smoke validation for selection, details loading, preview interaction, and diagnostics visibility - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java` -- new details controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` -- `prometeu-studio/src/main/java/p/studio/events/...` -- tests for details load state and section-local updates diff --git a/docs/studio/pull-requests/PR-07d-asset-mutation-and-structural-sync-orchestration.md b/docs/studio/pull-requests/PR-07d-asset-mutation-and-structural-sync-orchestration.md deleted file mode 100644 index b5102bb3..00000000 --- a/docs/studio/pull-requests/PR-07d-asset-mutation-and-structural-sync-orchestration.md +++ /dev/null @@ -1,83 +0,0 @@ -# PR-07d Asset Mutation and Structural Sync Orchestration - -Domain owner: `docs/studio` - -## Briefing - -Replace the current mutation flow that falls back to `refresh()` after many operations with an event-directed orchestration model. - -The key rule is: - -- local patches stay local; -- only structural workspace changes trigger structural sync; -- structural sync is explicit and typed, not an incidental rerender path. - -## Objective - -Make asset operations compatible with the event-driven component model. - -After this PR: - -- direct mutations publish patch or structural-sync events according to their actual impact; -- row and details controls react to targeted operation results when possible; -- create/remove/relocate or other structural operations request a workspace sync explicitly; -- the workspace no longer treats every successful operation as a reason to reload everything. -- the local-patch versus structural-sync rule is available as a reusable Studio workspace orchestration rule. - -## Dependencies - -- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md) -- [`./PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md) -- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md) -- [`./PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md) -- [`./PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md) - -## Scope - -- classify operations by update impact: - - local summary patch - - details patch - - structural workspace sync - - failure retention/reporting -- extract reusable orchestration helpers or contracts where the distinction is cross-workspace rather than asset-specific -- route mutation preview/apply results through typed events -- replace generic `refresh()` fallbacks for non-structural success paths -- keep progress/log/activity integration aligned with the new orchestration path -- make structural sync requests explicit and testable - -## Non-Goals - -- no redesign of packer service semantics -- no generic Studio-wide command bus abstraction in this slice -- no persistence work unrelated to asset-workspace orchestration - -## Execution Method - -1. Define operation-result events and structural-sync request events. -2. Map each mutation action to its update strategy. -3. Update mutation flows to publish events instead of directly forcing global workspace refresh. -4. Keep structural reload only for actions that truly change collection shape or asset identity. -5. Wire progress, logs, and activity to the new operation flow without reintroducing redraw coupling. - -## Acceptance Criteria - -- include/exclude, preload, and similar local operations can update via targeted events -- create/register/remove/relocate use explicit structural-sync flow only when required -- mutation preview and apply flows do not directly rebuild navigator and details by default -- activity/log/progress signals remain correct under the new orchestration -- the remaining structural sync path is narrow, explicit, and justified by actual data-shape changes -- the orchestration rule is documented as reusable Studio behavior, not an `Assets` exception - -## Validation - -- unit tests for operation-to-update-strategy mapping -- unit tests for structural-sync event publication -- unit tests for targeted patch propagation after successful operations -- UI smoke validation for register/include/exclude/relocate/remove flows - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java` -- mutation and orchestration classes under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` -- `prometeu-studio/src/main/java/p/studio/events/...` -- tests for mutation orchestration and structural sync behavior diff --git a/docs/studio/pull-requests/PR-07e-assets-refactor-cleanup-and-regression-coverage.md b/docs/studio/pull-requests/PR-07e-assets-refactor-cleanup-and-regression-coverage.md deleted file mode 100644 index a4b823f8..00000000 --- a/docs/studio/pull-requests/PR-07e-assets-refactor-cleanup-and-regression-coverage.md +++ /dev/null @@ -1,74 +0,0 @@ -# PR-07e Assets Refactor Cleanup and Regression Coverage - -Domain owner: `docs/studio` - -## Briefing - -Consolidate the refactor by removing obsolete redraw-heavy code paths, tightening naming, and locking the event-driven behavior with tests. - -## Objective - -Finish the corrective refactor so the codebase does not drift back toward monolithic render ownership. - -After this PR: - -- obsolete redraw-request and monolithic render helpers are removed; -- remaining component boundaries are clearer and easier to maintain; -- tests guard lifecycle, event routing, and selective-update behavior; -- the workspace code is organized around durable responsibilities rather than incremental leftovers. -- the resulting framework is left in a shape that other Studio workspaces can adopt directly. - -## Dependencies - -- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md) -- [`./PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md) -- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md) -- [`./PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md) - -## Scope - -- remove dead or transitional redraw-oriented code -- rename classes/events where the old naming reflects the wrong direction -- tighten package structure for navigator, details, and orchestration code -- make reusable framework pieces visible and discoverable to future workspace implementations -- add regression coverage for: - - lifecycle subscription hygiene - - selection propagation - - row patch propagation - - details-local updates - - structural sync boundaries -- update Studio learn/spec material if the refactor exposes terminology drift - -## Non-Goals - -- no new user-facing asset features in this slice -- no speculative refactor outside the `Assets` workspace and its direct event contracts - -## Execution Method - -1. Remove compatibility layers that existed only to bridge from the old refresh-heavy implementation. -2. Normalize class and event naming around lifecycle and event-driven ownership. -3. Reorganize tests to reflect component boundaries instead of one giant workspace class. -4. Update documentation to reflect the stabilized architecture. - -## Acceptance Criteria - -- the refactored `Assets` workspace no longer depends on redraw-request events as a primary mechanism -- code ownership is split along navigator, details, and orchestration boundaries -- lifecycle and event-driven behavior are covered by focused tests -- the remaining `AssetWorkspace` root is materially smaller and primarily compositional -- the reusable framework surface is clear enough for other workspaces to consume instead of cloning `Assets` internals - -## Validation - -- full unit-test pass for asset-workspace packages -- targeted regression tests for mount/unmount lifecycle safety -- targeted regression tests proving that local updates stay local unless structural sync is requested - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` -- `prometeu-studio/src/main/java/p/studio/events/...` -- `prometeu-studio/src/test/java/p/studio/workspaces/assets/...` -- `docs/studio/specs/4. Assets Workspace Specification.md` -- `docs/studio/learn/mental-model-assets-workspace.md` diff --git a/docs/studio/pull-requests/PR-08-assets-workspace-panel-package-boundaries-and-local-subscriptions.md b/docs/studio/pull-requests/PR-08-assets-workspace-panel-package-boundaries-and-local-subscriptions.md deleted file mode 100644 index dd1c268f..00000000 --- a/docs/studio/pull-requests/PR-08-assets-workspace-panel-package-boundaries-and-local-subscriptions.md +++ /dev/null @@ -1,117 +0,0 @@ -# PR-08 Assets Workspace Panel Package Boundaries and Local Subscriptions - -Domain owner: `docs/studio` - -## Briefing - -The current `Assets` workspace still keeps too much control logic concentrated in top-level workspace-area classes. - -That leaves package boundaries flatter than they should be and still weakens the intended Studio model: - -- every panel should own its own workspace-bus subscriptions; -- `AssetWorkspace` should stay as composition root and orchestration layer; -- the asset list should live in its own package area; -- the full right-hand details side should be split into package-owned panels with direct lifecycle-managed subscriptions. - -This refactor is a structural follow-up to the `PR-07` family. - -It does not redefine the event-driven direction; it completes it by enforcing package topology and subscription ownership at the panel level. - -## Objective - -Reorganize the `Assets` workspace into explicit package areas so that every list or details panel consumes the workspace event bus directly and subscribes only to the state it needs. - -After this PR: - -- `AssetWorkspace` composes package-scoped controls instead of hosting panel logic directly; -- all asset-list controls live under an `asset list` package area; -- the right-hand details side is organized under `details/...` package areas; -- `summary`, `actions`, `contract`, `preview`, and `diagnostics` each manage their own subscriptions; -- the package layout itself teaches the correct Studio workspace architecture. - -## Dependencies - -- [`./PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md) -- [`./PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md) -- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md) -- [`./PR-07e-assets-refactor-cleanup-and-regression-coverage.md`](./PR-07e-assets-refactor-cleanup-and-regression-coverage.md) -- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) - -## Scope - -- create an `asset list` package area under the `Assets` workspace implementation -- move the asset-list host and asset-list item control into that package area -- require both asset-list host and asset-list item to receive `StudioWorkspaceEventBus` -- require both asset-list host and asset-list item to own their own lifecycle-managed subscriptions -- create a `details` package area for the full right-hand side of the workspace -- split details internals into package-owned subareas such as: - - `details/summary` - - `details/actions` - - `details/contract` - - `details/preview` - - `details/diagnostics` -- require each details panel to subscribe directly to the event stream it consumes -- reduce coordinator-style pass-through logic where a child panel can consume the workspace bus directly -- keep shared details support code only where it removes real duplication without re-centralizing subscriptions - -## Non-Goals - -- no new mutation semantics -- no new global event-bus abstraction -- no visual redesign of the workspace -- no cross-workspace extraction unless a primitive is already justified by this refactor -- no return to top-level refresh orchestration as the normal update model - -## Execution Method - -1. Define the target package topology. - The package tree should reflect workspace areas, not arbitrary implementation convenience. - -2. Move asset-list code into a dedicated package area. - The list host and list item should be colocated and should consume the workspace bus directly. - -3. Normalize asset-list subscriptions. - The asset-list host should subscribe to list-level projection state. - The asset-list item should subscribe to item-local concerns such as selection and asset patch events. - -4. Move the full right-hand details side into a dedicated `details` package area. - The top-level details host should stay thin and should mount panel controls by workspace area. - -5. Split details panels by concern. - `summary`, `actions`, `contract`, `preview`, and `diagnostics` should each live in package-owned subareas and subscribe for themselves. - -6. Remove parent-owned update routing where it is only forwarding state to children. - If a child panel can subscribe to the workspace bus safely, it should do so directly. - -7. Re-check constructor contracts. - Every event-consuming panel should receive the `StudioWorkspaceEventBus` explicitly, plus only the interaction ports it truly needs. - -8. Clean naming and file layout. - Class names, package names, and placement should make the `Assets` workspace structure obvious to a new maintainer. - -## Acceptance Criteria - -- there is a dedicated package area for the asset list inside the `Assets` workspace -- asset-list host and asset-list item both receive `StudioWorkspaceEventBus` -- asset-list host and asset-list item both subscribe directly to the events they need -- there is a dedicated `details` package area for the right-hand workspace side -- `summary`, `actions`, `contract`, `preview`, and `diagnostics` each live in their own package-owned area -- each details panel owns its own lifecycle-managed subscriptions -- `AssetWorkspace` no longer acts as the effective subscriber for panel-internal state -- package structure and constructor boundaries make the lifecycle model explicit - -## Validation - -- unit tests for lifecycle subscribe/unsubscribe on moved controls -- unit tests or focused integration tests proving list item and details panels react from their own subscriptions -- regression validation that asset selection and local patch flows still update without workspace-wide refresh -- package-level review that no event-consuming panel is left without direct bus access - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java` -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` moved into list/details package areas -- asset-list controls under a dedicated list package -- details controls under `details/...` packages -- tests for workspace lifecycle and subscription ownership -- `docs/studio/specs/4. Assets Workspace Specification.md` if package/lifecycle wording needs tightening after the refactor diff --git a/docs/studio/pull-requests/PR-09-asset-move-action-and-relocate-wizard.md b/docs/studio/pull-requests/PR-09-asset-move-action-and-relocate-wizard.md deleted file mode 100644 index 21c32661..00000000 --- a/docs/studio/pull-requests/PR-09-asset-move-action-and-relocate-wizard.md +++ /dev/null @@ -1,164 +0,0 @@ -# PR-09 Asset Move Action and Relocate Wizard - -Domain owner: `docs/studio` - -## Briefing - -Adicionar a action `Move` na área de actions do asset selecionado e conectá-la a um wizard de relocação explícita. - -O usuário deve escolher o destino do asset e revisar um resumo antes da execução. -Depois da confirmação, o Studio não move diretórios localmente. -Ele apenas envia um comando de relocação para o packer, que passa a ser o owner completo da mudança: - -- atualiza o estado interno necessário; -- move o diretório do asset dentro da árvore `assets` do projeto; -- emite eventos operacionais até a conclusão. - -Este plano também fecha uma regra operacional que precisa existir nas duas pontas: - -- o diretório destino final do asset não pode já ser um root de asset; -- portanto, o root destino não pode conter `asset.json`. - -Após a confirmação do resumo, o modal deve entrar em estado de espera com spinner, escutando o evento operacional do packer. -Quando a operação terminar: - -- sucesso: o Studio dispara refresh, fecha o modal e reposiciona a seleção; -- falha: o modal sai do estado de espera e mostra a falha sem fechar silenciosamente. - -## Objective - -Entregar um fluxo de `Move` que seja explícito, previsível e compatível com o modelo em que o packer executa a mutação real e o Studio apenas comanda e observa. - -Após este PR: - -- a seção `Actions` do selected asset expõe `Move`; -- clicar em `Move` abre um wizard dedicado; -- o wizard coleta o parent de destino e o nome final do diretório; -- o wizard mostra um passo final de resumo antes do comando final; -- o Studio não aceita um destino cujo root já contenha `asset.json`; -- o packer também rejeita esse destino como regra de segurança e conformance; -- a confirmação final envia um comando de relocation para o packer via API; -- o modal entra em espera com spinner até receber o evento terminal da operação; -- o refresh estrutural só ocorre depois do evento de conclusão do packer. - -## Dependencies - -- [`./PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md) -- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md) -- [`./PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md) -- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) -- cross-domain reference: [`../../packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md`](../../packer/pull-requests/PR-05-sensitive-mutations-preview-apply-and-studio-write-adapter.md) -- cross-domain reference: [`../../packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md`](../../packer/pull-requests/PR-09-event-lane-progress-and-studio-operational-integration.md) - -## Scope - -- adicionar a action `Move` na seção `Actions` do details -- introduzir um `Relocate Wizard` efetivamente utilizável pelo selected asset atual -- coletar destino por: - - parent directory - - destination name - - target root derivado -- mostrar passo final de resumo antes da confirmação -- enviar um comando `RELOCATE_ASSET` com `targetRoot` explícito para o packer -- abrir estado modal de espera com spinner após confirmação -- correlacionar a operação via `operationId` -- escutar o evento operacional do packer até `ACTION_APPLIED` ou `ACTION_FAILED` -- publicar structural sync explícito apenas após conclusão bem-sucedida -- validar no Studio que `targetRoot/asset.json` não exista -- validar no packer que `targetRoot/asset.json` não exista, mesmo se o Studio falhar em bloquear antes - -## Non-Goals - -- não redesenhar o mutation preview panel inteiro -- não introduzir rename inline fora do wizard -- não adicionar batch move -- não redefinir semântica de identidade do asset -- não permitir fallback para target automático quando o usuário iniciou `Move` -- não mover diretórios diretamente pelo Studio fora do comando ao packer - -## Execution Method - -1. Expor `Move` na seção `Actions`. - O botão deve existir apenas quando houver asset selecionado e deve abrir o wizard a partir do `AssetReference` atual. - -2. Implementar o wizard de relocação como fluxo explícito de destino. - O wizard deve reutilizar a linguagem já existente de `relocateWizard` e coletar: - - root atual - - diretório parent de destino - - nome final do diretório - - target root calculado - -3. Adicionar validação local de destino. - O wizard deve bloquear avanço/confirmação quando: - - o target root for igual ao root atual; - - o target root sair da área válida esperada; - - o target root já contiver `asset.json`. - -4. Adicionar passo final de resumo. - Antes do comando final, o usuário deve ver um resumo do: - - asset atual - - root atual - - parent de destino - - nome final - - target root resultante - -5. Integrar o wizard ao fluxo de comando assíncrono do packer. - A saída do wizard deve virar `PackerMutationRequest(RELOCATE_ASSET, ..., targetRoot)`, sem usar target automático. - Depois do `OK`, o Studio inicia a operação, captura o `operationId` retornado e coloca o modal em estado de espera. - -6. Esperar conclusão por evento, não por refresh cego. - O modal deve escutar `StudioPackerOperationEvent` correlacionado por `operationId`. - Regras: - - `ACTION_APPLIED`: disparar refresh estrutural, fechar modal e reselecionar o asset relocado; - - `ACTION_FAILED`: sair do spinner, manter modal aberto e mostrar a falha; - - eventos intermediários como `PROGRESS_UPDATED` podem atualizar a mensagem/estado visual, mas não fecham o modal. - -7. Endurecer a regra no packer. - O preview/apply de relocation deve recusar destino cujo root já contenha `asset.json`, produzindo blocker claro e estável. - -8. Orquestrar o pós-conclusão como mudança estrutural. - Relocation bem-sucedida deve acionar sync estrutural explícito e reposicionar a seleção para o asset movido no novo root. - -## Acceptance Criteria - -- `Move` aparece na seção `Actions` do asset selecionado -- clicar em `Move` abre wizard dedicado em vez de mutação imediata -- o wizard exige destino explícito escolhido pelo usuário -- existe passo final de resumo antes da conclusão -- `targetRoot/asset.json` bloqueia o fluxo já no Studio -- o packer também bloqueia `targetRoot/asset.json` como regra de segurança -- o `OK` final envia o comando ao packer e coloca o modal em espera com spinner -- o modal só fecha depois de `ACTION_APPLIED` para a mesma operação -- falha operacional não fecha o modal silenciosamente -- sucesso operacional executa structural sync explícito -- a seleção final aponta para o asset já movido, não para o root antigo - -## Validation - -- unit tests para validação de target root no wizard -- unit tests para derivação de `targetRoot` a partir de parent + destination name -- unit tests para correlação `operationId -> modal state` -- unit tests para sucesso/falha dirigidos por `StudioPackerOperationEvent` -- unit tests para publication/orchestration de relocation como structural sync -- packer tests para blocker quando `targetRoot/asset.json` já existe -- smoke test de UI para: - - abrir `Move` - - editar destino - - ver resumo final - - bloquear destino inválido - - confirmar operação - - ver spinner de espera - - fechar no evento de sucesso - - manter aberto no evento de falha - -## Affected Artifacts - -- `docs/studio/specs/4. Assets Workspace Specification.md` se a regra de destino inválido precisar ser tornada mais explícita -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/actions/...` -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/wizards/...` -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` mutation orchestration wiring -- `prometeu-studio/src/main/java/p/studio/events/...` -- `prometeu-studio/src/main/resources/i18n/messages.properties` -- `prometeu-packer/src/main/java/p/packer/mutations/...` -- testes de Studio para wizard/flow -- testes de packer para relocation target validation diff --git a/docs/studio/pull-requests/PR-10a-bank-composition-details-dto-projection.md b/docs/studio/pull-requests/PR-10a-bank-composition-details-dto-projection.md deleted file mode 100644 index 5dad5144..00000000 --- a/docs/studio/pull-requests/PR-10a-bank-composition-details-dto-projection.md +++ /dev/null @@ -1,81 +0,0 @@ -# PR-10a Bank Composition Details DTO Projection - -Domain owner: `docs/studio` -Cross-domain impact: `docs/packer` - -## Briefing - -Introduce the Studio-owned DTO projection boundary for `Bank Composition` inside `Asset Details`. - -This slice converts runtime/details source data into section-facing DTOs before any new section UI or middleware is added. - -The goal is to land the data boundary first, so the UI work that follows does not bind directly to snapshot rows or raw `asset.json` shapes. - -## Objective - -After this PR: - -- `Asset Details` has a Studio-owned DTO family for `Bank Composition`; -- snapshot-derived data feeds `available` rows; -- persisted selection data feeds `selected` rows; -- only non-blocking files reach the `available` DTO list; -- selected ordering is represented in a way that can later map to explicit persisted indexes. - -## Dependencies - -- [`../decisions/Bank Composition Details DTO Projection Decision.md`](../decisions/Bank%20Composition%20Details%20DTO%20Projection%20Decision.md) -- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md) -- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md) - -## Scope - -- add the Studio DTO family for bank-composition rows and section data -- map details/snapshot source data into: - - `available` - - `selected` -- start the DTO field set with: - - `path` - - `displayName` - - `size` - - `lastModified` - - `fingerprint` - - `metadata` -- filter blocking files out of the `available` projection -- ensure selected ordering is available to the UI as ordered row state - -## Non-Goals - -- no new section UI yet -- no dual-list component yet -- no capacity meter yet -- no staged-edit coordinator yet -- no persistence/apply integration yet - -## Execution Method - -1. Introduce the DTO types for bank-composition details data. -2. Extend the details projection path to populate `available` and `selected`. -3. Filter blocking files before DTO emission. -4. Preserve selected ordering in the section-facing projection. -5. Add regression tests around DTO mapping and filtering. - -## Acceptance Criteria - -- `Asset Details` can provide Studio-owned `Bank Composition` DTOs without exposing raw packer internals to the section -- `available` rows come from current runtime/details data -- blocking files do not appear in `available` -- `selected` rows are available as ordered data -- the new DTO projection is ready for subsequent section and component slices - -## Validation - -- unit tests for DTO mapping from details/snapshot source data -- unit tests for blocking-file exclusion -- unit tests for selected-row ordering preservation - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...` -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/...` -- tests for details projection and DTO mapping -- cross-domain touchpoint: packer-facing details DTO shaping if source data is still missing diff --git a/docs/studio/pull-requests/PR-10b-bank-composition-base-components.md b/docs/studio/pull-requests/PR-10b-bank-composition-base-components.md deleted file mode 100644 index b2a1e46f..00000000 --- a/docs/studio/pull-requests/PR-10b-bank-composition-base-components.md +++ /dev/null @@ -1,75 +0,0 @@ -# PR-10b Bank Composition Base Components - -Domain owner: `docs/studio` - -## Briefing - -Introduce the base UI building blocks for `Bank Composition`: - -- `StudioDualListView` -- `StudioAssetCapacityMeter` - -This slice lands the named components with intentionally narrow first-wave APIs, before section-shell wiring or behavior orchestration. - -## Objective - -After this PR: - -- `StudioDualListView` exists as an abstract Studio component; -- the first asset-details concrete dual-list implementation exists; -- `StudioAssetCapacityMeter` exists as a dumb vertical meter component; -- right-list ordering support includes `moveUp`, `moveDown`, and visible indices. - -## Dependencies - -- [`../decisions/Bank Composition Base Components Decision.md`](../decisions/Bank%20Composition%20Base%20Components%20Decision.md) -- [`../decisions/Bank Composition Details DTO Projection Decision.md`](../decisions/Bank%20Composition%20Details%20DTO%20Projection%20Decision.md) -- [`./PR-10a-bank-composition-details-dto-projection.md`](./PR-10a-bank-composition-details-dto-projection.md) - -## Scope - -- add abstract `StudioDualListView` -- add the first asset-details-specific concrete dual-list implementation -- add dumb `StudioAssetCapacityMeter` -- support row rendering directly in the concrete dual-list implementation -- support right-list index display -- support `moveUp` and `moveDown` affordances in the component contract - -## Non-Goals - -- no section shell yet -- no `FormSession` integration yet -- no family-specific capacity rules inside components -- no workspace-bus contract yet -- no apply persistence - -## Execution Method - -1. Add the abstract dual-list base component. -2. Add the first concrete asset-details implementation against the new DTOs. -3. Add the capacity meter component with: - - `progress` - - label - - severity band - - optional hint text -4. Add component tests for rendering, ordering affordances, and meter state display. - -## Acceptance Criteria - -- the codebase contains the new named base components for `Bank Composition` -- the first concrete dual-list implementation works against Studio DTOs -- the right/build list can show visible indices -- the component contract exposes `moveUp` and `moveDown` -- the capacity meter can render absolute progress and severity state without owning bank rules - -## Validation - -- unit tests for dual-list rendering and ordering controls -- unit tests for visible index updates -- unit tests for capacity-meter state rendering - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/controls/...` -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...` -- tests for dual-list and capacity meter components diff --git a/docs/studio/pull-requests/PR-10c-bank-composition-section-shell-and-form-session-integration.md b/docs/studio/pull-requests/PR-10c-bank-composition-section-shell-and-form-session-integration.md deleted file mode 100644 index 441b5bc9..00000000 --- a/docs/studio/pull-requests/PR-10c-bank-composition-section-shell-and-form-session-integration.md +++ /dev/null @@ -1,70 +0,0 @@ -# PR-10c Bank Composition Section Shell and Form Session Integration - -Domain owner: `docs/studio` - -## Briefing - -Add the `Bank Composition` section shell into `Asset Details`, aligned with `Runtime Contract` and the existing `StudioFormSession` section rhythm. - -This slice lands the visible section and its staged-edit shell contract before full family-specific behavior is wired. - -## Objective - -After this PR: - -- `Asset Details` contains a real `Bank Composition` section; -- the section is a `VBox` section aligned with the existing details composition; -- the section mirrors the `Runtime Contract` shell as closely as practical; -- the section exposes `change`, `apply`, `reset`, and `cancel`; -- outside editing it renders persisted state in read-only mode; -- before behavior wiring is complete it can still render disabled/read-only internals instead of looking absent. - -## Dependencies - -- [`../decisions/Bank Composition Section Shell Decision.md`](../decisions/Bank%20Composition%20Section%20Shell%20Decision.md) -- [`./PR-10a-bank-composition-details-dto-projection.md`](./PR-10a-bank-composition-details-dto-projection.md) -- [`./PR-10b-bank-composition-base-components.md`](./PR-10b-bank-composition-base-components.md) -- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md) - -## Scope - -- add the `Bank Composition` section to `Asset Details` -- align the shell with `Runtime Contract` -- integrate `StudioFormSession` staged-edit lifecycle at the section boundary -- render read-only or disabled internals when behavior is incomplete -- show persisted state outside edit mode - -## Non-Goals - -- no family-specific bank rules yet -- no final section-scoped coordinator yet -- no workspace-bus events yet -- no packer apply write path yet - -## Execution Method - -1. Introduce the section host into `Asset Details`. -2. Reuse the existing section/action-bar rhythm from `Runtime Contract`. -3. Bind the section shell to a `StudioFormSession` lifecycle. -4. Render read-only state outside edit mode. -5. Render disabled/read-only internals where behavior is still pending. - -## Acceptance Criteria - -- the `Bank Composition` section is visible in `Asset Details` -- the section shell matches the existing details-section rhythm -- `change`, `apply`, `reset`, and `cancel` are part of the shell contract -- outside edit mode the section shows persisted state in read-only form -- the section does not appear blank or absent while later slices are still pending - -## Validation - -- unit tests for section visibility and shell state -- unit tests for `StudioFormSession`-driven shell transitions -- UI smoke validation for read-only and editing shell modes - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java` -- new bank-composition section controls under `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...` -- tests for details section-shell lifecycle diff --git a/docs/studio/pull-requests/PR-10d-bank-composition-family-policies-and-section-coordinator.md b/docs/studio/pull-requests/PR-10d-bank-composition-family-policies-and-section-coordinator.md deleted file mode 100644 index d7798cf7..00000000 --- a/docs/studio/pull-requests/PR-10d-bank-composition-family-policies-and-section-coordinator.md +++ /dev/null @@ -1,77 +0,0 @@ -# PR-10d Bank Composition Family Policies and Section Coordinator - -Domain owner: `docs/studio` -Cross-domain impact: `docs/packer` - -## Briefing - -Introduce the section-scoped coordinator for `Bank Composition`, built around `StudioFormSession`, plus the first family-specific draft factories and policies. - -This is the slice where the section starts behaving like an actual editor instead of just a shell. - -## Objective - -After this PR: - -- `Bank Composition` has a section-scoped coordinator built around `StudioFormSession`; -- the section can enter edit mode and maintain draft state; -- draft state can transfer rows between `available` and `selected`; -- right-list ordering can update draft state; -- family-specific rules are applied through draft factories and policies, not component-local logic. - -## Dependencies - -- [`../decisions/Bank Composition Middleware and Staged Editing Decision.md`](../decisions/Bank%20Composition%20Middleware%20and%20Staged%20Editing%20Decision.md) -- [`./PR-10a-bank-composition-details-dto-projection.md`](./PR-10a-bank-composition-details-dto-projection.md) -- [`./PR-10b-bank-composition-base-components.md`](./PR-10b-bank-composition-base-components.md) -- [`./PR-10c-bank-composition-section-shell-and-form-session-integration.md`](./PR-10c-bank-composition-section-shell-and-form-session-integration.md) - -## Scope - -- add `BankCompositionDraft` -- add the section-scoped coordinator around `StudioFormSession` -- add family-specific draft factories -- add family-specific policies for: - - transfer eligibility - - reorder effects - - capacity usage - - hard-limit blockers -- publish one section-facing view model for shell, lists, meter, blockers, and hints - -## Non-Goals - -- no public `workspaceBus` contract yet -- no packer apply persistence yet -- no final cross-domain mutation messages yet - -## Execution Method - -1. Add the draft model for bank composition. -2. Add the section-scoped coordinator around `StudioFormSession`. -3. Add the first family-specific policy/factory implementations. -4. Route dual-list and meter inputs through the coordinator view model. -5. Support edit, reset, and cancel with real draft recomputation. -6. Keep apply stubbed or disabled until the write path lands. - -## Acceptance Criteria - -- the section can enter editing mode and maintain draft state -- dual-list moves update draft state through the coordinator -- right-list ordering updates draft state through the coordinator -- meter state reflects policy-driven capacity calculations -- tile and sound family differences are modeled through policies, not through component branches -- `reset` and `cancel` work through `StudioFormSession` - -## Validation - -- unit tests for `BankCompositionDraft` -- unit tests for tile and sound policy behavior -- unit tests for transfer blocking and reorder effects -- unit tests for `StudioFormSession` integration and draft lifecycle - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...` -- family-specific policy and draft-factory classes under `prometeu-studio/src/main/java/p/studio/workspaces/assets/...` -- tests for coordinator and policy behavior -- cross-domain touchpoint: any details data gaps exposed by the new policy logic diff --git a/docs/studio/pull-requests/PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md b/docs/studio/pull-requests/PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md deleted file mode 100644 index 54bdafe4..00000000 --- a/docs/studio/pull-requests/PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md +++ /dev/null @@ -1,70 +0,0 @@ -# PR-10e Bank Composition WorkspaceBus Events and Local Orchestration - -Domain owner: `docs/studio` - -## Briefing - -Connect the `Bank Composition` section-scoped coordinator to the Studio workspace event model using the minimal notification-oriented contract already decided. - -This slice keeps user actions local while making draft, capacity, and apply lifecycle visible to the rest of the workspace when needed. - -## Objective - -After this PR: - -- the section keeps user commands local to the section-scoped coordinator; -- the minimal `workspaceBus` notifications exist for bank-composition state changes; -- external observers can react to draft, capacity, and apply lifecycle without owning section-local commands. - -## Dependencies - -- [`../decisions/Bank Composition WorkspaceBus Interaction Decision.md`](../decisions/Bank%20Composition%20WorkspaceBus%20Interaction%20Decision.md) -- [`./PR-10d-bank-composition-family-policies-and-section-coordinator.md`](./PR-10d-bank-composition-family-policies-and-section-coordinator.md) - -## Scope - -- add the first public bank-composition events: - - `BankCompositionDraftChanged` - - `BankCompositionCapacityChanged` - - `BankCompositionApplyRequested` - - `BankCompositionApplied` - - `BankCompositionApplyFailed` -- keep section-local actions local to the coordinator -- publish capacity notifications with: - - `progress` - - `severity` - - `blocked` -- wire section subscribers/publishers as needed inside `Asset Details` - -## Non-Goals - -- no conversion of all section actions into public bus commands -- no cross-workspace event taxonomy expansion beyond the minimal first-wave set -- no packer write-path implementation in this slice - -## Execution Method - -1. Add the event classes and payloads. -2. Publish draft and capacity notifications from the coordinator. -3. Publish apply-requested/applied/apply-failed lifecycle notifications at the right boundaries. -4. Keep move/reorder/edit/reset/cancel orchestration local. -5. Add tests for event publication and subscription behavior. - -## Acceptance Criteria - -- the minimal first-wave bank-composition events exist on `workspaceBus` -- user actions such as move and reorder are not exposed as public bus commands -- capacity events publish absolute `0..1` progress plus severity and blocked state -- apply lifecycle notifications are observable outside the section - -## Validation - -- unit tests for event publication -- unit tests for event payload correctness -- unit tests confirming section-local actions remain local - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/events/...` -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...` -- tests for bank-composition event flow diff --git a/docs/studio/pull-requests/PR-10f-bank-composition-apply-through-packer-and-snapshot-refresh.md b/docs/studio/pull-requests/PR-10f-bank-composition-apply-through-packer-and-snapshot-refresh.md deleted file mode 100644 index 54c5d885..00000000 --- a/docs/studio/pull-requests/PR-10f-bank-composition-apply-through-packer-and-snapshot-refresh.md +++ /dev/null @@ -1,76 +0,0 @@ -# PR-10f Bank Composition Apply Through Packer and Snapshot Refresh - -Domain owner: `docs/studio` -Cross-domain impact: `docs/packer` - -## Briefing - -Close the write path for `Bank Composition` by routing `apply` through the packer service and rebinding the section from refreshed persisted state. - -This is the slice where the section stops being draft-only and becomes a real persisted editor. - -## Objective - -After this PR: - -- clicking `apply` sends the selected ordered files to packer; -- packer owns validation, manifest persistence, and minimal runtime snapshot refresh; -- `asset.json` persistence flows through `artifacts`, not `inputsByRole`; -- successful apply rebinds the section from refreshed persisted state; -- failed apply preserves the draft and keeps the section in editing mode. - -## Dependencies - -- [`../decisions/Bank Composition Persistence and Snapshot Propagation Decision.md`](../decisions/Bank%20Composition%20Persistence%20and%20Snapshot%20Propagation%20Decision.md) -- [`./PR-10d-bank-composition-family-policies-and-section-coordinator.md`](./PR-10d-bank-composition-family-policies-and-section-coordinator.md) -- [`./PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md`](./PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md) -- cross-domain dependency: packer-side message, persistence, and snapshot-refresh support for bank-composition apply - -## Scope - -- route section `apply` through the packer service boundary -- send selected ordered files from Studio to packer -- persist selection through `asset.json` `artifacts` -- refresh minimal runtime/details state after successful apply -- rebind the section from refreshed persisted state -- preserve draft state on apply failure -- surface local failure state plus `BankCompositionApplyFailed` - -## Non-Goals - -- no direct `asset.json` writes from Studio -- no fallback write path through legacy `inputsByRole` -- no broader manifest migration outside this flow - -## Execution Method - -1. Define the Studio-to-packer apply request path for bank composition. -2. Integrate section `apply` with the packer service. -3. Update the Studio side to await success/failure and rebind accordingly. -4. Land the paired packer-side persistence and minimal snapshot refresh support. -5. Add regression tests for success and failure behavior. - -## Acceptance Criteria - -- Studio does not write `asset.json` directly for bank composition -- `apply` is executed by packer -- selected ordered files are persisted through `artifacts` -- after success, the section leaves edit mode and reloads from refreshed persisted state -- after failure, the section stays in edit mode and the draft is preserved -- apply lifecycle notifications reflect the actual result of the packer call - -## Validation - -- Studio unit tests for apply success rebinding -- Studio unit tests for apply failure preserving draft state -- packer tests for `artifacts` persistence and minimal snapshot refresh -- UI smoke validation for apply, success, and failure flows - -## Affected Artifacts - -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...` -- `prometeu-studio/src/main/java/p/studio/projects/...` -- `prometeu-studio/src/main/java/p/studio/events/...` -- `prometeu-packer/src/main/java/p/packer/...` -- `asset.json` persistence handling under the packer write path -- Studio and packer tests for bank-composition apply diff --git a/docs/studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md b/docs/studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md deleted file mode 100644 index f739bf66..00000000 --- a/docs/studio/pull-requests/PR-11-pack-wizard-shell-and-packer-contract-consumption.md +++ /dev/null @@ -1,166 +0,0 @@ -# PR-11 Pack Wizard Shell and Packer Contract Consumption - -Domain owner: `docs/studio` -Cross-domain impact: `docs/packer` - -## Briefing - -The `Pack` action in the `Assets` workspace is now closed as a Studio wizard over packer-owned operations. - -The Studio decision already fixes the operational boundary: - -- Studio is the shell; -- packer owns summary, validation, pack execution, progress, and result semantics; -- the wizard has four phases: - `Summary`, `Validation`, `Packing`, `Result`; -- validation runs only on the current `registered + included in build` set; -- blocking diagnostics stop the flow before execution; -- the first wave is non-cancelable. - -The packer-side API PR also defines the contracts that Studio must consume: - -- pack summary -- pack validation -- pack execution - -This PR implements the Studio side of that contract. - -References: - -- [`../decisions/Pack Wizard in Assets Workspace Decision.md`](../decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md) -- [`../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md) - -## Objective - -Deliver the `Pack` wizard shell in the `Assets` workspace and bind it to the public packer contracts for summary, validation, progress, and result. - -## Dependencies - -- [`../decisions/Pack Wizard in Assets Workspace Decision.md`](../decisions/Pack%20Wizard%20in%20Assets%20Workspace%20Decision.md) -- [`./PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md) -- [`./PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md) -- [`./PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md) -- cross-domain reference: - [`../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](../../packer/pull-requests/PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md) - -## Scope - -- add a real `Pack` action entry point in the `Assets` workspace action bar -- open a dedicated modal wizard from that button -- implement the wizard shell with four explicit phases: - - `Summary` - - `Validation` - - `Packing` - - `Result` -- consume packer summary API for the first phase -- consume packer validation API for the second phase -- consume packer pack execution API for the third phase -- bind packer operation progress to the wizard progress UI -- render result data from the final pack execution response -- show blocking diagnostics by default in `Validation` -- allow developer drill-down on per-asset validation entries -- keep `Packing` non-editable and non-cancelable in the first wave -- keep companion artifacts in secondary drill-down in `Result` -- allow a `dumb` future-facing export/copy button without real behavior if the shell needs a visible reminder - -## Non-Goals - -- no local Studio recomputation of build-set semantics -- no local Studio validation engine for pack gating -- no fake timer-based progress -- no cancellation in the first wave -- no direct implementation of packer semantics inside Studio -- no asset-details-local `Pack`; this remains a workspace-level flow - -## Execution Method - -1. Wire the `Pack` action in the workspace action bar to open the new wizard. - -2. Build a dedicated wizard shell control for the `Assets` workspace. - The shell should own: - - phase navigation - - modal presentation - - loading states - - error surfaces - - binding to packer responses and progress events - -3. Implement the `Summary` phase as packer-backed preflight. - Rules: - - request pack summary on open; - - do not reconstruct counts from navigator rows; - - show the canonical artifact name `assets.pa`; - - show the build-set counts returned by packer. - -4. Implement the `Validation` phase as packer-backed gate inspection. - Rules: - - call the validation API explicitly; - - render aggregate counts and per-asset entries; - - show blocking diagnostics by default; - - allow drill-down to inspect more context on each asset; - - block advance into `Packing` when validation fails. - -5. Implement the `Packing` phase as an operational waiting surface. - Rules: - - call pack execution explicitly only after successful validation; - - show progress bar and current-step text from packer-driven state; - - keep the modal non-editable; - - do not expose real cancel behavior in the first wave. - -6. Implement the `Result` phase as packer-result rendering. - Rules: - - show final status; - - show total assets packed; - - show elapsed time when available from the contract; - - keep `assets.pa` visible in the main summary; - - move companion artifacts into secondary drill-down. - -7. Integrate the operation with Studio progress and activity surfaces where appropriate. - The wizard-local progress surface is primary during execution, but existing global operational surfaces should remain coherent with the same operation. - -8. Keep the implementation boundary strict. - Studio may orchestrate calls and render states, but it must not decide: - - what the pack set is; - - what counts as blocking; - - how `asset_table` ordering is determined; - - or what artifacts were emitted beyond what packer reports. - -## Acceptance Criteria - -- clicking `Pack` in the `Assets` workspace opens a dedicated modal wizard -- the wizard has explicit `Summary`, `Validation`, `Packing`, and `Result` phases -- `Summary` is populated from packer summary data rather than local UI reconstruction -- `Validation` is populated from packer validation data -- validation failure blocks transition into `Packing` -- blocking diagnostics are visible by default in the validation phase -- per-asset drill-down exists for developer inspection -- `Packing` shows packer-driven progress and remains non-editable -- the first wave does not expose real cancellation -- `Result` renders final packer result data and keeps companion artifacts secondary -- the Studio implementation remains a shell over packer contracts rather than a second semantic engine - -## Validation - -- unit tests for wizard phase state transitions -- unit tests for mapping summary response into the `Summary` phase -- unit tests for validation gating and blocked advance into `Packing` -- unit tests for per-asset validation drill-down state -- unit tests for progress binding from packer operation state into the wizard progress UI -- unit tests for result rendering from pack execution response -- smoke test for: - - open wizard - - load summary - - run validation - - stop on blockers - - advance on valid state - - show packing progress - - render final result - -## Affected Artifacts - -- `docs/studio/specs/4. Assets Workspace Specification.md` if the wizard shell behavior needs more explicit normative wording -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java` -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/**` -- `prometeu-studio/src/main/java/p/studio/workspaces/assets/wizards/**` -- `prometeu-studio/src/main/java/p/studio/events/**` if new UI-local orchestration events are needed -- `prometeu-studio/src/main/resources/i18n/messages.properties` -- `prometeu-studio/src/test/java/p/studio/workspaces/assets/**` diff --git a/docs/studio/pull-requests/README.md b/docs/studio/pull-requests/README.md index 7abbf4f0..7d726806 100644 --- a/docs/studio/pull-requests/README.md +++ b/docs/studio/pull-requests/README.md @@ -2,6 +2,12 @@ This directory contains executable plans for Studio work. +Current retained set: + +- none + +The previous Studio execution wave has already been consolidated into [`../learn/`](../learn/) and propagated into [`../specs/`](../specs/). + ## Purpose A Studio pull-request or plan artifact packages a decision into an implementable sequence. @@ -36,37 +42,5 @@ A Studio plan should usually include: ## Current Queue -The current Studio execution queue is: - -1. [`PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md) -2. [`PR-05b-asset-navigator-search-filters-and-selection.md`](./PR-05b-asset-navigator-search-filters-and-selection.md) -3. [`PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md) -4. [`PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md) -5. [`PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md) -6. [`PR-07a-assets-event-topology-and-lifecycle-foundation.md`](./PR-07a-assets-event-topology-and-lifecycle-foundation.md) -7. [`PR-07b-asset-navigator-and-row-subscriptions.md`](./PR-07b-asset-navigator-and-row-subscriptions.md) -8. [`PR-07c-asset-details-and-form-lifecycle.md`](./PR-07c-asset-details-and-form-lifecycle.md) -9. [`PR-07d-asset-mutation-and-structural-sync-orchestration.md`](./PR-07d-asset-mutation-and-structural-sync-orchestration.md) -10. [`PR-07e-assets-refactor-cleanup-and-regression-coverage.md`](./PR-07e-assets-refactor-cleanup-and-regression-coverage.md) -11. [`PR-08-assets-workspace-panel-package-boundaries-and-local-subscriptions.md`](./PR-08-assets-workspace-panel-package-boundaries-and-local-subscriptions.md) -12. [`PR-06-project-scoped-studio-state-and-activity-persistence.md`](./PR-06-project-scoped-studio-state-and-activity-persistence.md) - -The `PR-07` family is a corrective refactor pass for the current `Assets` implementation. -It exists to replace the refresh-heavy direction with lifecycle-managed, event-driven ownership. -It also establishes the intended Studio-wide workspace framework, with `Assets` as the first consumer and proof point. - -`PR-08` is the package-topology and subscription-ownership follow-up for that same direction. -It enforces list/details package boundaries and requires every panel to consume the workspace bus directly. - -Recommended execution order: - -`PR-05a -> PR-05b -> PR-05c -> PR-05d -> PR-05e -> PR-07a -> PR-07b -> PR-07c -> PR-07d -> PR-07e -> PR-08 -> PR-06` - -Next planned family for `Bank Composition`: - -13. [`PR-10a-bank-composition-details-dto-projection.md`](./PR-10a-bank-composition-details-dto-projection.md) -14. [`PR-10b-bank-composition-base-components.md`](./PR-10b-bank-composition-base-components.md) -15. [`PR-10c-bank-composition-section-shell-and-form-session-integration.md`](./PR-10c-bank-composition-section-shell-and-form-session-integration.md) -16. [`PR-10d-bank-composition-family-policies-and-section-coordinator.md`](./PR-10d-bank-composition-family-policies-and-section-coordinator.md) -17. [`PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md`](./PR-10e-bank-composition-workspacebus-events-and-local-orchestration.md) -18. [`PR-10f-bank-composition-apply-through-packer-and-snapshot-refresh.md`](./PR-10f-bank-composition-apply-through-packer-and-snapshot-refresh.md) +When a new Studio execution wave starts, add only the plans that still represent pending work. +Do not repopulate this directory with already-absorbed historical implementation slices.