test(packer): qualify asset contracts and improve Jenkins reporting

This commit is contained in:
2026-10-16 11:47:58 +01:00
parent 13c0ababbb
commit 91eb86f317
8 changed files with 506 additions and 51 deletions
@@ -0,0 +1,85 @@
---
id: LSN-0082
ticket: packer-runtime-graphics-conformance
title: Packer Contracts and CI Failure Evidence
created: 2026-10-16
tags: [packer, studio, testing, jenkins]
---
# Packer Contracts and CI Failure Evidence
## Original problem and scope
A broad runtime-readiness audit suggested graphics integration qualification,
but historical review did not establish a new asset format migration. Existing
Studio work already covered RGBA8888, scene identity and variable palettes.
The actual opportunity was to strengthen producer-boundary evidence and ensure
CI preserved useful results when tests failed.
Owner: packer; transverse owner: Studio Gradle/Jenkins infrastructure. The user
explicitly excluded runtime provisioning in Jenkins and all new automated
runtime tests, including local ones. Existing games remain the manual integrated
verification method. This lesson does not claim those games were run.
## Consolidated decision and implementation
The packer's ordinary Java/JUnit suite now checks complete serialized GLYPH
payloads for tile sizes 8/16/32 and palette counts 1/3/64, using independently
authored hex expectations. Alpha, ordinary index zero and high-first nibble
order are compared as bytes. A complete four-layer SCENE fixture covers
little-endian identity, parallax, flags/flips and decoded-size accounting.
An out-of-range palette cannot publish a new artifact.
A mixed-asset test reads the embedded header of assets.pa, checks sidecar
agreement and proves that all payload slices cover the file contiguously.
Two GLYPH preloads use slots 0/1 while SCENE uses its own slot 0; a fourth
asset is deliberately not preloaded. AssetId 16909060 remains the scene's
cold dependency even though the glyph preload slot is 1. These identities
must not be conflated.
Jenkins now uses the repository wrapper, headless JVMs and a separate clean
stage. Verification uses --continue: independent tests and reports complete,
but Gradle still fails on test failure. Unconditional post handling isolates
JUnit, coverage, HTML and archive publishers. Missing evidence after a successful
verification is an error; failed preparation does not publish old reports.
Existing coverage thresholds and their UNSTABLE policy remain unchanged.
No production writer change was necessary.
## Evidence and limits
Studio base: 13c0ababbb0ff8623eb4df671729a891788b1ab1. Contract reference:
runtime f7d7c167531bb662a1af9d73fc326bb476bf8aa7. Validation on 2026-10-16:
- Packer suite: 119 tests passed, zero skips; five new contract cases included.
- Ordinary headless repository run: 897 tests, two failures, 13 existing skips.
Consolidated JaCoCo XML and HTML were generated despite test failure.
- Failures in unchanged files: PbsGradleDependencyAllowlistTest rejects the
existing build-pipeline testImplementation PBS dependency; McpContractTest
rejects an existing tool exampleArguments contract. The complete repository
test gate is not green; these failures were not suppressed by this change.
- Groovy 4.0.29 parsed the Jenkinsfile. Seven local step-double scenarios passed:
success, test failure, publisher failure, missing contract report, absent
reports on success/failure and clean failure. This does not validate actual
controller plugins or constitute a Jenkins job run.
- git diff --check and discussion validate passed.
No runtime invocation, automated frame comparison or manual gameplay was
performed. Producer bytes passing these assertions do not prove live loading
or presentation. Report manual game/revision/actions/results only after play.
## Pitfalls
- Deriving expected bytes through the production writer makes an oracle circular.
- Checking only exported JSON misses corruption in the embedded artifact header.
- Publishing reports only after a successful shell step hides failure diagnostics.
- Allowing empty reports on successful verification can turn absent execution into
apparent success. Allow absence only when the build already failed.
- A broad contract corpus is not a reason to duplicate existing tests or port a
runtime decoder into Java. Keep checks at the producer's actual output boundary.
## References
- [Fixture interpretation and commands](../../../prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/README.md).
- [CI commands and failure behavior](../../../files/config/README.md).
- [Build artifact specification](../../../docs/specs/packer/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md).
- Completed workflow provenance: AGD-0079, DEC-0066, PLN-0145 (housekept after implementation).
+75 -51
View File
@@ -1,68 +1,92 @@
pipeline {
agent any
tools {
gradle 'gradle-9.3.1'
}
environment {
GRADLE_USER_HOME = '/var/jenkins_home/.gradle'
GRADLE_OPTS = '-Dorg.gradle.parallel=true -Dorg.gradle.caching=true'
JAVA_TOOL_OPTIONS = '-Djava.awt.headless=true'
JAVA_OPTS = '-Xmx2g'
TESTS_STARTED = 'false'
VERIFICATION_SUCCEEDED = 'false'
}
stages {
stage('Build') {
stage('Clean') {
steps {
// A separate successful clean prevents publishing a previous build's reports.
withGradle {
sh './gradlew clean --no-daemon --console=plain'
}
}
}
stage('Tests and coverage') {
steps {
script { env.TESTS_STARTED = 'true' }
withChecks(name: 'Test', includeStage: true) {
withGradle {
sh """
gradle \
clean \
test \
jacocoTestReport \
--parallel \
--max-workers=2 \
--build-cache \
--no-daemon
"""
// --continue finishes independent tests/reports but retains a nonzero exit on failure.
sh './gradlew test jacocoTestReport --continue --parallel --max-workers=2 --build-cache --no-daemon --console=plain'
}
junit testResults: '**/build/test-results/test/TEST-*.xml'
}
withChecks(name: 'JaCoCo Coverage', includeStage: false) {
recordCoverage(tools: [[parser: 'JACOCO', pattern: "build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml"]],
id: 'jacoco',
name: 'JaCoCo Coverage',
checksName: 'JaCoCo Coverage',
sourceDirectories: [[path: 'glob:**/src/main/java']],
sourceCodeEncoding: 'UTF-8',
sourceCodeRetention: 'EVERY_BUILD',
qualityGates: [
[threshold: 50.0, metric: 'CLASS', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 50.0, metric: 'METHOD', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 50.0, metric: 'LINE', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 50.0, metric: 'INSTRUCTION', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 40.0, metric: 'BRANCH', baseline: 'PROJECT', criticality: 'UNSTABLE']])
}
script { env.VERIFICATION_SUCCEEDED = 'true' }
}
} // Test
stage('Reports') {
steps {
script {
// archiveArtifacts artifacts: '**/coverage-sources.zip', allowEmptyArchive: false, fingerprint: false, onlyIfSuccessful: false
publishHTML (target: [
allowMissing: true,
alwaysLinkToLastBuild: false,
keepAll: true,
reportDir: "build/reports/jacoco/jacocoTestReport/html",
reportFiles: 'index.html',
reportName: 'Coverage Report'
])
// def pmd = scanForIssues tool: [$class: 'Pmd'], pattern: 'lib/build/reports/pmd/*.xml'
// publishIssues issues: [pmd]
}
}
} // Reports
}
}
}
post {
always {
script {
if (env.TESTS_STARTED == 'true') {
// Isolate publishers so a failed publisher does not suppress the other diagnostics.
catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
junit testResults: '**/build/test-results/test/TEST-*.xml',
allowEmptyResults: env.VERIFICATION_SUCCEEDED != 'true'
if (env.VERIFICATION_SUCCEEDED == 'true' && !fileExists('prometeu-packer/prometeu-packer-v1/build/test-results/test/TEST-p.packer.services.PackerAssetContractTest.xml')) {
error 'Successful verification is missing the packer contract test report.'
}
}
catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
if (fileExists('build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml')) {
withChecks(name: 'JaCoCo Coverage', includeStage: false) {
recordCoverage(tools: [[parser: 'JACOCO', pattern: 'build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml']],
id: 'jacoco',
name: 'JaCoCo Coverage',
checksName: 'JaCoCo Coverage',
sourceDirectories: [[path: 'glob:**/src/main/java']],
sourceCodeEncoding: 'UTF-8',
sourceCodeRetention: 'EVERY_BUILD',
qualityGates: [
[threshold: 50.0, metric: 'CLASS', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 50.0, metric: 'METHOD', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 50.0, metric: 'LINE', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 50.0, metric: 'INSTRUCTION', baseline: 'PROJECT', criticality: 'UNSTABLE'],
[threshold: 40.0, metric: 'BRANCH', baseline: 'PROJECT', criticality: 'UNSTABLE']])
}
} else if (env.VERIFICATION_SUCCEEDED == 'true') {
error 'Successful verification is missing the consolidated JaCoCo XML report.'
} else {
echo 'Verification failed before consolidated coverage was available; preserving available test reports.'
}
}
catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
publishHTML(target: [
allowMissing: env.VERIFICATION_SUCCEEDED != 'true',
alwaysLinkToLastBuild: false,
keepAll: true,
reportDir: 'build/reports/jacoco/jacocoTestReport/html',
reportFiles: 'index.html',
reportName: 'Coverage Report'
])
}
catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
archiveArtifacts artifacts: '**/build/test-results/test/**, **/build/reports/tests/test/**, **/build/reports/jacoco/**',
allowEmptyArchive: env.VERIFICATION_SUCCEEDED != 'true',
onlyIfSuccessful: false
}
} else {
echo 'Preparation did not complete; no current test run to publish. See the build console for diagnostics.'
}
}
}
}
}
+57
View File
@@ -0,0 +1,57 @@
# Studio Jenkins verification
`Jenkinsfile` uses the checked-in Gradle wrapper (currently 9.3.1). A compatible
Java installation must be available to launch Gradle; project conventions select
Java 21 for compilation/tests. The pipeline retains its existing Gradle cache
location, worker limit and installed Jenkins report plugins. It does not require
a named Jenkins Gradle installation.
The build runs on a Unix agent with Java and dependency/cache access. It sets
`JAVA_TOOL_OPTIONS=-Djava.awt.headless=true` for Gradle and test JVMs. No display,
runtime binary, sibling runtime checkout, runtime download/build, or new Jenkins
plugin is required by the packer contract suite.
## Commands
```sh
export JAVA_TOOL_OPTIONS=-Djava.awt.headless=true
./gradlew clean --no-daemon --console=plain
./gradlew test jacocoTestReport --continue --parallel --max-workers=2 --build-cache --no-daemon --console=plain
```
Clean is a separate stage: when it fails, old reports must not be published as a
new test run. Gradle `--continue` lets independent tasks and reports finish after
a test failure; it does not turn a failing command into success. Runtime/desktop
opt-in test tasks are not invoked. The ordinary packer `test` task includes
`PackerAssetContractTest` without skips or a runtime fallback.
## Failure reporting
The unconditional post block publishes available JUnit, consolidated JaCoCo XML,
HTML and archived test/coverage reports after a failed verification command.
Each publisher is isolated so one publisher error does not prevent the others
from being attempted. The build console retains compilation/setup diagnostics.
An otherwise successful verification must produce JUnit results, the packer
contract suite report, consolidated JaCoCo XML and HTML. Missing successful-build
evidence fails publication. A failed compilation may have no reports: the
original build failure remains authoritative and available diagnostics are still
preserved. A failed clean does not publish potentially stale artifacts.
Coverage thresholds are unchanged: CLASS/METHOD/LINE/INSTRUCTION 50%, BRANCH
40%, PROJECT baseline and UNSTABLE criticality. Reports from partially failed
test runs are useful diagnostics, not a passing quality gate.
## Contract and manual verification boundary
See the packer fixture [provenance and coverage](../../prometeu-packer/prometeu-packer-v1/src/test/resources/fixtures/contracts/README.md).
The automated suite checks producer bytes and metadata against independent
expectations. Runtime gameplay remains manual with existing games, not a local
or CI automated test. Record manual outcomes only after execution.
Local Gradle checks and Groovy parsing cannot certify controller plugin behavior.
A Jenkins run is needed to observe actual report publication and coverage checks;
report any unavailable controller validation explicitly.
Jenkins behavior references: [post conditions](https://www.jenkins.io/doc/book/pipeline/syntax/#post)
and [catchError](https://www.jenkins.io/doc/pipeline/steps/workflow-basic-steps/#catcherror-catch-error-and-set-build-result-to-failure).
@@ -0,0 +1,219 @@
package p.packer.services;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import p.packer.messages.*;
import p.packer.repositories.*;
import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Arrays;
import java.util.HexFormat;
import java.util.List;
import java.util.Objects;
import static org.junit.jupiter.api.Assertions.*;
/** Producer contract checks only: no runtime executable or runtime decoder. */
final class PackerAssetContractTest {
private static final ObjectMapper JSON = new ObjectMapper();
private static final int[] COLORS = {0x123456ff, 0xabcdef80, 0x34567800, 0x876543ff};
@TempDir Path projectRoot;
@ParameterizedTest
@CsvSource({"8,1", "16,3", "32,64"})
void glyphPayloadMatchesIndependentNibblesAndRgba(int tileSize, int paletteCount) throws Exception {
glyph(7, tileSize, paletteCount, true);
registry(7);
final Envelope packed = pack();
final JsonNode entry = packed.header().path("asset_table").get(0);
assertEquals("GLYPH", entry.path("bank_type").asText());
assertEquals("NONE", entry.path("codec").asText());
assertEquals(tileSize, entry.path("metadata").path("tile_size").asInt());
assertEquals(256, entry.path("metadata").path("width").asInt());
assertEquals(256, entry.path("metadata").path("height").asInt());
assertEquals(paletteCount, entry.path("metadata").path("palette_count").asInt());
assertEquals(32768 + paletteCount * 64, entry.path("size").asInt());
assertEquals(65536 + paletteCount * 64, entry.path("decoded_size").asInt());
assertArrayEquals(expectedGlyph(tileSize, paletteCount), packed.slice(entry));
}
@Test
void embeddedHeaderAddressesMultipleAssetsAndPreloadsByBankIdentity() throws Exception {
glyph(7, 8, 1, true);
glyph(33, 8, 1, false);
glyph(16909060, 8, 1, true);
scene(99);
// Deliberately unsorted registry; asset identity must not become list index or slot.
registry(16909060, 99, 33, 7);
final Envelope packed = pack();
final JsonNode entries = packed.header().path("asset_table");
assertEquals(List.of(7, 33, 99, 16909060),
java.util.stream.StreamSupport.stream(entries.spliterator(), false)
.map(e -> e.path("asset_id").asInt()).toList());
assertEquals(JSON.readTree("""
[{"asset_id":7,"slot":0},{"asset_id":99,"slot":0},{"asset_id":16909060,"slot":1}]
"""), packed.header().path("preload"));
int end = 0;
for (JsonNode entry : entries) {
assertEquals(end, entry.path("offset").asInt(), "offset is payload-relative and contiguous");
assertEquals("NONE", entry.path("codec").asText());
if (entry.path("asset_id").asInt() == 99) {
assertEquals("SCENE", entry.path("bank_type").asText());
assertEquals(1, entry.path("metadata").path("version").asInt());
assertEquals(4, entry.path("metadata").path("layer_count").asInt());
assertEquals(96, entry.path("decoded_size").asInt()); // 4 * (16 overhead + 8 tile)
assertArrayEquals(hex("scene-v1.hex"), packed.slice(entry));
} else {
assertArrayEquals(expectedGlyph(8, 1), packed.slice(entry));
}
end += entry.path("size").asInt();
}
assertEquals(packed.bytes().length, packed.payloadOffset() + end, "no unaddressed/trailing payload");
}
@Test
void invalidPaletteCannotPublishAnAssetArtifact() throws Exception {
glyph(7, 8, 1, true);
registry(7);
Path manifestPath = asset(7).resolve("asset.json");
ObjectNode manifest = (ObjectNode) JSON.readTree(manifestPath.toFile());
((ObjectNode) manifest.path("output").path("pipeline").path("palettes").get(0)).put("index", 64);
JSON.writeValue(manifestPath.toFile(), manifest);
final var result = service().packWorkspace(new PackWorkspaceRequest(project()));
assertEquals(PackerOperationStatus.PARTIAL, result.status());
assertTrue(result.result().emittedArtifacts().isEmpty());
assertFalse(Files.exists(projectRoot.resolve("build/assets.pa")));
}
private Envelope pack() throws Exception {
final var result = service().packWorkspace(new PackWorkspaceRequest(project()));
assertEquals(PackerOperationStatus.SUCCESS, result.status(), result.toString());
final byte[] bytes = Files.readAllBytes(projectRoot.resolve("build/assets.pa"));
final ByteBuffer prelude = ByteBuffer.wrap(bytes).order(ByteOrder.LITTLE_ENDIAN);
assertArrayEquals(new byte[]{'A', 'S', 'P', 'A'}, Arrays.copyOf(bytes, 4));
assertEquals(1, prelude.getInt(4));
int headerLength = prelude.getInt(8);
assertTrue(headerLength > 0);
assertEquals(32L + headerLength, prelude.getLong(12));
assertArrayEquals(new byte[12], Arrays.copyOfRange(bytes, 20, 32));
int payloadOffset = Math.toIntExact(prelude.getLong(12));
JsonNode header = JSON.readTree(Arrays.copyOfRange(bytes, 32, payloadOffset));
assertEquals(JSON.readTree(projectRoot.resolve("build/asset_table.json").toFile()), header.path("asset_table"));
assertEquals(JSON.readTree(projectRoot.resolve("build/preload.json").toFile()), header.path("preload"));
return new Envelope(bytes, header, payloadOffset);
}
private record Envelope(byte[] bytes, JsonNode header, int payloadOffset) {
byte[] slice(JsonNode entry) {
int start = payloadOffset + entry.path("offset").asInt();
int end = start + entry.path("size").asInt();
assertTrue(start >= payloadOffset && end <= bytes.length);
return Arrays.copyOfRange(bytes, start, end);
}
}
private byte[] expectedGlyph(int tileSize, int palettes) throws Exception {
byte[] expected = new byte[32768 + palettes * 64];
// Fixed 256-pixel sheet: repeat the independently authored 8-pixel row in the first tile.
byte[] row = hex("glyph-row.hex");
for (int y = 0; y < tileSize; y++) {
for (int x = 0; x < tileSize / 8; x++) {
System.arraycopy(row, 0, expected, y * 128 + x * 4, row.length);
}
}
byte[] colors = hex("glyph-colors.hex");
for (int palette = 0; palette < palettes; palette++) {
System.arraycopy(colors, 0, expected, 32768 + palette * 64, colors.length);
}
return expected;
}
private void glyph(int id, int tileSize, int palettes, boolean preload) throws Exception {
ObjectNode manifest = manifest(id, "glyph_bank", "GLYPH/indexed_v1", preload);
ObjectNode output = (ObjectNode) manifest.path("output");
output.putObject("metadata").put("tile_size", tileSize + "x" + tileSize);
ArrayNode table = output.putObject("pipeline").putArray("palettes");
for (int p = 0; p < palettes; p++) {
ObjectNode palette = table.addObject().put("index", p);
ArrayNode colors = palette.putObject("palette").putArray("rgba8888");
for (int color : COLORS) colors.add(color);
}
manifest.putArray("artifacts").addObject().put("file", "tile.png").put("index", 0);
JSON.writeValue(asset(id).resolve("asset.json").toFile(), manifest);
BufferedImage image = new BufferedImage(tileSize, tileSize, BufferedImage.TYPE_INT_ARGB);
for (int y = 0; y < tileSize; y++) {
for (int x = 0; x < tileSize; x++) {
int rgba = COLORS[x % 4];
image.setRGB(x, y, (rgba >>> 8) | (rgba << 24));
}
}
assertTrue(ImageIO.write(image, "png", asset(id).resolve("tile.png").toFile()));
}
private void scene(int id) throws Exception {
JSON.writeValue(asset(id).resolve("asset.json").toFile(), manifest(id, "scene_bank", "SCENE/tilemap_v1", true));
ObjectNode request = JSON.createObjectNode().put("schema_version", 1).put("format", "SCENE/tilemap_v1").put("version", 1);
ArrayNode layers = request.putArray("layers");
for (int i = 0; i < 4; i++) {
ObjectNode layer = layers.addObject().put("active", true).put("glyph_asset_id", 16909060)
.put("tile_size", 8).put("parallax_factor_x", 1.0).put("parallax_factor_y", 0.5)
.put("width", 1).put("height", 1);
layer.putArray("tiles").addObject().put("active", true).put("glyph_id", i)
.put("palette_id", 0).put("flip_x", (i & 1) != 0).put("flip_y", (i & 2) != 0);
}
JSON.writeValue(asset(id).resolve("scene-bank.pack-request.json").toFile(), request);
}
private ObjectNode manifest(int id, String type, String format, boolean preload) throws Exception {
Files.createDirectories(asset(id));
ObjectNode manifest = JSON.createObjectNode().put("schema_version", 1).put("asset_uuid", "contract-" + id)
.put("name", "asset_" + id).put("type", type);
manifest.putObject("output").put("format", format).put("codec", "NONE");
manifest.putObject("preload").put("enabled", preload);
return manifest;
}
private void registry(int... ids) throws Exception {
Path path = projectRoot.resolve("assets/.prometeu/index.json");
Files.createDirectories(path.getParent());
ObjectNode registry = JSON.createObjectNode().put("schema_version", 1).put("next_asset_id", 16909061);
ArrayNode assets = registry.putArray("assets");
for (int id : ids) assets.addObject().put("asset_id", id).put("asset_uuid", "contract-" + id)
.put("root", "asset-" + id).put("included_in_build", true);
JSON.writeValue(path.toFile(), registry);
}
private Path asset(int id) { return projectRoot.resolve("assets/asset-" + id); }
private PackerProjectContext project() { return new PackerProjectContext("contract", projectRoot); }
private byte[] hex(String name) throws Exception {
try (var input = Objects.requireNonNull(getClass().getResourceAsStream("/fixtures/contracts/" + name))) {
return HexFormat.of().parseHex(new String(input.readAllBytes(), StandardCharsets.UTF_8).replaceAll("\\s", ""));
}
}
private FileSystemPackerWorkspaceService service() {
var foundation = new PackerWorkspaceFoundation(JSON);
var parser = new PackerAssetDeclarationParser(JSON);
var cache = new FileSystemPackerCacheRepository(JSON);
var materializer = new PackerRuntimeAssetMaterializer(new PackerAssetWalker(JSON));
var registry = new PackerRuntimeRegistry(new PackerRuntimeLoader(foundation, parser, cache, materializer));
var resolver = new PackerAssetReferenceResolver(foundation.lookup());
return new FileSystemPackerWorkspaceService(JSON, foundation,
new PackerAssetDetailsService(registry, resolver),
new PackerAssetActionReadService(registry, resolver, foundation.lookup()),
new PackerRuntimePatchService(parser, materializer), registry, cache,
new PackerProjectWriteCoordinator(), event -> {});
}
}
@@ -0,0 +1,59 @@
# Packer binary contract fixtures
These expectations are authored from the published wire contract, independently
of the Java writer. They are not captured from packer output. Tests call the real
`packWorkspace` service and read the embedded header and payload of `assets.pa`;
JSON sidecars alone are not the oracle.
Reference snapshot: runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`:
- `docs/specs/runtime/15-asset-management.md`, sections 3–4 and 9;
- `crates/console/prometeu-hal/src/asset.rs`, scene layout constants;
- `crates/console/prometeu-drivers/src/asset/decode.rs`, nibble and channel order.
The Studio producer's fixed 256×256 sheet and asset envelope are documented in
`docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`.
No runtime checkout, executable or decoder is needed to execute these tests.
## Fixture interpretation
- `glyph-row.hex`: eight indexed pixels `0,1,2,3,0,1,2,3`, high nibble first.
The test repeats this row within the first 8/16/32-pixel tile and leaves the
rest of the 256×256 sheet at index zero.
- `glyph-colors.hex`: four independent RGBA colors, including opaque index zero,
partial alpha at index one, transparent index two and distinct channel values.
Each palette has these four colors followed by twelve zero entries. Tests
exercise 1, 3 and 64 palettes and compare the entire serialized bank.
- `scene-v1.hex`: a 12-byte SCNE/version-1/four-layer header followed by four
32-byte layer headers and one four-byte tile per layer. All layers are active,
use glyph AssetId `0x01020304` (16909060, not its preload slot 1), tile size 8,
parallax (1.0, 0.5), width/height/count 1 and zero reserved fields. Tile flags
are 1/3/5/7, exercising both flip bits; palette is zero and glyph IDs are
0/1/2/3. Serialized size is 156; decoded size is 4 × (16 + 8) = 96.
The mixed-asset test includes an asset with preload disabled and two GLYPH
preloads in slots 0/1 plus a SCENE preload in slot 0. It checks payload-relative
nonzero offsets, stable IDs, no payload gaps/trailing bytes, and equality between
the embedded header and exported sidecars. The invalid-palette case verifies
that palette index 64 cannot publish a new `assets.pa`.
Existing `FileSystemPackerWorkspaceServiceTest` coverage remains responsible for
basic emission, sparse palettes, material remapping, frozen snapshots and
selected SCENE fields. These fixtures complement those tests at the complete
artifact boundary rather than porting the runtime's decoder corpus.
## Execution and limits
```sh
./gradlew :prometeu-packer:prometeu-packer-v1:test --tests '*PackerAssetContractTest'
```
The suite also runs under ordinary `./gradlew test`. ImageIO uses in-memory
images and temporary files; no display is needed. Fixtures never launch a
runtime, skip for missing runtime, or fall back to a simulated runtime.
Passing these tests demonstrates producer contract coverage, not runtime
loading/rendering. Integrated verification is manual using existing games.
Record the game, Studio/runtime revisions, actions and observed result when
that verification is actually performed; do not infer a gameplay pass from
these byte comparisons.
@@ -0,0 +1 @@
123456ff abcdef80 34567800 876543ff
@@ -0,0 +1,9 @@
53434e45 0100 0400 00000000
01 04030201 08 0000 0000803f 0000003f 01000000 01000000 01000000 00000000
01 00 0000
01 04030201 08 0000 0000803f 0000003f 01000000 01000000 01000000 00000000
03 00 0100
01 04030201 08 0000 0000803f 0000003f 01000000 01000000 01000000 00000000
05 00 0200
01 04030201 08 0000 0000803f 0000003f 01000000 01000000 01000000 00000000
07 00 0300