219 lines
11 KiB
Markdown
219 lines
11 KiB
Markdown
# 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<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 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/<operation-id>/`;
|
|
- `<operation-id>` 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.
|