clean up
This commit is contained in:
@@ -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<PackerProbeResult> 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/<operation-id>/` as the first-wave staging location;
|
||||
- `<operation-id>` 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/<operation-id>/` 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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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`.
|
||||
Reference in New Issue
Block a user